Libcontainer

https://docs.rs/libcontainer/0.6.0/
Admin
Libcontainer is a Rust library that provides container management primitives including process...
Tokens:293,680
Snippets:2,292
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create and Start a Container

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/struct.Container.html

Demonstrates how to create a new container using ContainerBuilder and then start it. Ensure the necessary paths and syscall types are correctly configured.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.start();
```

--------------------------------

### MainSender: Notify Network Setup Ready

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/channel.rs.html

Notifies the main process that the network setup is ready.

```rust
pub fn network_setup_ready(&mut self) -> Result<(), ChannelError> {
    tracing::debug!("notify network setup ready");
    self.sender.send(Message::SetupNetworkDeviceReady)?;

    Ok(())
}
```

--------------------------------

### Start a Container

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container_start.rs.html

Demonstrates how to create and start a container using ContainerBuilder. This is typically used in the init process of a container.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

# fn main() -> anyhow::Result<()> {
let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.start();
# Ok(())
# }
```

--------------------------------

### Send Signal to Container Init Process

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container_kill.rs.html

Demonstrates how to create a container and then send a SIGKILL signal to its init process. This example requires a running container setup.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;
use nix::sys::signal::Signal;

# fn main() -> anyhow::Result<()> {
let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.kill(Signal::SIGKILL, false)?;
# Ok(())
# }

```

--------------------------------

### Setup Basic Memory Policy

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/memory_policy.rs.html

Applies a basic memory policy with MPOL_BIND mode to nodes 0 and 1. Asserts that the setup is successful.

```rust
let policy = LinuxMemoryPolicyBuilder::default()
            .mode(MemoryPolicyModeType::MpolBind)
            .nodes("0,1".to_string())
            .flags(vec![])
            .build()
            .unwrap();

        assert!(setup_memory_policy(&Some(policy), syscall.as_ref()).is_ok());
```

--------------------------------

### Container::start

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/struct.Container.html

Starts a previously created container.

```APIDOC
## pub fn start

### Description
Starts a previously created container.

### Returns
- `Result<(), LibcontainerError>` - Ok if the container was started successfully, or a LibcontainerError.
```

--------------------------------

### Setup Envs Method Signature

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/workload/trait.Executor.html

The `setup_envs` method is provided by the Executor trait to set environment variables for the container process. It runs after initial setup and before the start signal. Host environment variables are not cleared by default.

```rust
fn setup_envs(
        &self,
        envs: HashMap<String, String>,
    ) -> Result<(), ExecutorSetEnvsError> { ... }
```

--------------------------------

### Test Setup Console Socket

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/tty.rs.html

Tests the successful setup of a console socket. It binds a Unix listener, calls `setup_console_socket`, and asserts that a valid file descriptor is returned.

```rust
use std::os::unix::net::UnixListener;

use anyhow::{Ok, Result};
use serial_test::serial;

use super::*;

const CONSOLE_SOCKET: &str = "console-socket";

#[test]
#[serial]
fn test_setup_console_socket() -> Result<()> {
    let testdir = tempfile::tempdir()?;
    let socket_path = Path::join(testdir.path(), "test-socket");
    let lis = UnixListener::bind(&socket_path);
    assert!(lis.is_ok());
    let fd = setup_console_socket(testdir.path(), &socket_path, CONSOLE_SOCKET)?;
    assert_ne!(fd.as_raw_fd(), -1);
    Ok(())
}
```

--------------------------------

### Example of Deleting a Container

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container_delete.rs.html

Demonstrates how to initialize and delete a container. This example shows the typical usage pattern for removing a container, including the `force` parameter.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

# fn main() -> anyhow::Result<()> {
let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.delete(true)?;
# Ok(())
# }

```

--------------------------------

### Signal Network Setup Ready

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/process/channel/struct.MainSender.html

Indicates that the network setup for the process is complete. This should be called after all network interfaces and configurations have been applied.

```rust
pub fn network_setup_ready(&mut self) -> Result<(), ChannelError>
```

--------------------------------

### Example: Valid /proc Mount Check

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/mount.rs.html

Demonstrates a valid scenario for checking if a mount destination is `/proc`. This example assumes the destination is an absolute path with symlinks resolved.

```rust
    /// # Example  (a valid case where `/proc` is mounted with `proc` type.)
    ///
    /// ```
    /// use std::path::PathBuf;
    /// use oci_spec::runtime::MountBuilder as SpecMountBuilder;
    /// use libcontainer::rootfs::Mount;
    ///
    /// let mounter = Mount::new();
    ///
    /// let rootfs = PathBuf::from("/var/lib/my-runtime/containers/abcd1234/rootfs");
    /// let destination = PathBuf::from("/proc");
    /// let source = PathBuf::from("proc");
    /// let typ = "proc";
    ///
    /// let mount = SpecMountBuilder::default()
    ///
```

--------------------------------

### Test cgroup mount setup

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/mount.rs.html

Verifies the correct mount arguments are generated for a cgroup2 filesystem mount.

```rust
let mut mounter = Mount::new();
        let tmp = tempfile::tempdir()?;
        let container_cgroup = PathBuf::from("cgroup");

        let expected = MountArgs {
            source: Some(PathBuf::from("cgroup".to_owned())),
            target: tmp.path().join_safely(container_cgroup)?,
            fstype: Some("cgroup2".to_owned()),
            flags: MsFlags::MS_NOEXEC | MsFlags::MS_NOSUID | MsFlags::MS_NODEV,
            data: Some("".to_owned()),
        };

        let got = mounter
            .syscall
            .as_any()
            .downcast_ref::<TestHelperSyscall>()
            .unwrap()
            .get_mount_args();

        assert_eq!(got.len(), 1);
        assert_eq!(expected, got[0]);

        Ok(())
    }
```

--------------------------------

### Setup /dev/kcore Symlink

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Conditionally creates a symbolic link for /dev/kcore if the /proc/kcore file exists. This is architecture-dependent.

```rust
    pub fn setup_kcore_symlink(&self, rootfs: &Path) -> Result<()> {
        if Path::new("/proc/kcore").exists() {
            self.syscall
                .symlink(Path::new("/proc/kcore"), &rootfs.join("dev/kcore"))
                .map_err(|err| {
                    tracing::error!("failed to symlink kcore");
                    SymlinkError::Syscall { source: err }
                })?;
        }
        Ok(())
    }
```

--------------------------------

### Initialize ContainerBuilder

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/builder.rs.html

Creates a new ContainerBuilder with default settings. Use this to start configuring a container.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

let builder = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
);

```

--------------------------------

### Create Container and Notify Start

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/tenant_builder.rs.html

Creates a container using the builder and notifies the system that the container has started. It includes logic to handle potential errors during creation and notification.

```rust
        let pid = builder_impl.create()?;

        let mut notify_socket = NotifySocket::new(notify_path);
        notify_socket.notify_container_start()?;

        // Explicitly close the write end of the pipe here to notify the
        // `read_end` that the init process is able to move forward. Closing one
        // end of the pipe will immediately signal the other end of the pipe,
        // which we use in the init thread as a form of barrier.  `drop` is used
        // here because `OwnedFd` supports it, so we don't have to use `close`
        // here with `RawFd`.
        drop(write_end);

        let mut err_str_buf = Vec::new();

        loop {
            let mut buf = [0; 3];
            match read(read_end.as_raw_fd(), &mut buf).map_err(LibcontainerError::OtherSyscall)? {
                0 => {
                    if err_str_buf.is_empty() {
                        return Ok(pid);
                    } else {
                        return Err(LibcontainerError::Other(
                            String::from_utf8_lossy(&err_str_buf).to_string(),
                        ));
                    }
                }
                _ => {
                    err_str_buf.extend(buf);
                }
            }
        }
```

--------------------------------

### Container Intermediate Process Setup

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/container_intermediate_process.rs.html

This function orchestrates the setup of a container's intermediate process. It configures namespaces, applies cgroup settings, and manages CPU affinity before and after cgroup modifications. It's crucial for preparing the environment for the init process.

```rust
pub fn container_intermediate_process(
    args: &ContainerArgs,
    intermediate_chan: &mut (channel::IntermediateSender, channel::IntermediateReceiver),
    init_chan: &mut (channel::InitSender, channel::InitReceiver),
    main_sender: &mut channel::MainSender,
) -> Result<()> {
    let (inter_sender, inter_receiver) = intermediate_chan;
    let (init_sender, init_receiver) = init_chan;
    let command = args.syscall.create_syscall();
    let spec = &args.spec;
    let linux = spec.linux().as_ref().ok_or(MissingSpecError::Linux)?;
    let namespaces = Namespaces::try_from(linux.namespaces().as_ref())?;
    let cgroup_manager = libcgroups::common::create_cgroup_manager(args.cgroup_config.to_owned())
        .map_err(|e| IntermediateProcessError::Cgroup(e.to_string()))?;

    let current_pid = Pid::this();
    // setting CPU affinity for tenant container before cgroup move
    if matches!(args.container_type, ContainerType::TenantContainer { .. }) {
        if let Some(exec_cpu_affinity) = spec
            .process()
            .as_ref()
            .and_then(|p| p.exec_cpu_affinity().as_ref())
        {
            if let Some(initial) = exec_cpu_affinity.initial() {
                cpu_affinity::set_cpuset_affinity_from_string(current_pid, initial)?;
            }
        }
    }
    let _ = cpu_affinity::log_cpu_affinity();

    // this needs to be done before we create the init process, so that the init
    // process will already be captured by the cgroup. It also needs to be done
    // before we enter the user namespace because if a privileged user starts a
    // rootless container on a cgroup v1 system we can still fulfill resource
    // restrictions through the cgroup fs support (delegation through systemd is
    // not supported for v1 by us). This only works if the user has not yet been
    // mapped to an unprivileged user by the user namespace however.
    // In addition this needs to be done before we enter the cgroup namespace as
    // the cgroup of the process will form the root of the cgroup hierarchy in
    // the cgroup namespace.
    apply_cgroups(
        &cgroup_manager,
        linux.resources().as_ref(),
        matches!(args.container_type, ContainerType::InitContainer),
    )?;

    // setting CPU affinity for tenant container after cgroup move
    if matches!(args.container_type, ContainerType::TenantContainer { .. }) {
        if let Some(exec_cpu_affinity) = spec
            .process()
            .as_ref()
            .and_then(|p| p.exec_cpu_affinity().as_ref())
        {
            if let Some(cpu_affinity_final) = exec_cpu_affinity.cpu_affinity_final() {
                cpu_affinity::set_cpuset_affinity_from_string(current_pid, cpu_affinity_final)?;
            }
        }
    }

    // if new user is specified in specification, this will be true and new
    // namespace will be created, check
    // https://man7.org/linux/man-pages/man7/user_namespaces.7.html for more
    // information
    if let Some(user_namespace) = namespaces.get(LinuxNamespaceType::User)? {
        setup_userns(&namespaces, user_namespace, main_sender, inter_receiver)?;

        // After UID and GID mapping is configured correctly in the Youki main
        // process, We want to make sure continue as the root user inside the

```

--------------------------------

### Notify Container Start

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/notify_socket.rs.html

Connects to a Unix domain socket and sends a 'start container' message. It changes the current directory to the parent of the socket path before connecting and restores it afterward.

```rust
fn notify_container_start(&mut self) -> Result<(), NotifyListenerError> {
        tracing::debug!("notify container start");
        let cwd = env::current_dir().map_err(NotifyListenerError::GetCwd)?;
        let workdir = self
            .path
            .parent()
            .ok_or_else(|| NotifyListenerError::InvalidPath(self.path.to_owned()))?;
        unistd::chdir(workdir).map_err(|e| NotifyListenerError::Chdir {
            source: e,
            path: workdir.to_owned(),
        })?;
        let socket_name = self
            .path
            .file_name()
            .ok_or_else(|| NotifyListenerError::InvalidPath(self.path.to_owned()))?;
        let mut stream = 
            UnixStream::connect(socket_name).map_err(|e| NotifyListenerError::Connect {
                source: e,
                // ok to unwrap as OsStr should always be utf-8 compatible
                name: socket_name.to_str().unwrap().to_owned(),
            })?;
        stream
            .write_all(b"start container")
            .map_err(NotifyListenerError::SendStartContainer)?;
        tracing::debug!("notify finished");
        unistd::chdir(&cwd).map_err(|e| NotifyListenerError::Chdir {
            source: e,
            path: cwd,
        })?;
        Ok(())
    }
}
```

--------------------------------

### Wait for Network Setup Ready

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/channel.rs.html

Waits for a `Message::SetupNetworkDeviceReady` message. Returns an error for unexpected messages or receive failures.

```rust
pub fn wait_for_network_setup_ready(&mut self) -> Result<(), ChannelError> {
        let msg = self
            .receiver
            .recv()
            .map_err(|err| ChannelError::ReceiveError {
                msg: "waiting for init ready".to_string(),
                source: err,
            })?;
        match msg {
            Message::SetupNetworkDeviceReady => Ok(()),
            msg => Err(ChannelError::UnexpectedMessage {
                expected: Message::SetupNetworkDeviceReady,
                received: msg,
            }),
        }
    }
```

--------------------------------

### Child Process Setup and Fork

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/container_main_process.rs.html

Sets the process dumpable state, creates a new user namespace, and requests identifier mapping from the parent.

```rust
prctl::set_dumpable(true).unwrap();
unshare(CloneFlags::CLONE_NEWUSER)?;
parent_sender.identifier_mapping_request()?;
parent_sender.close()?;
child_receiver.wait_for_mapping_ack()?;
child_receiver.close()?;
std::process::exit(0);
```

--------------------------------

### Delete Container Example

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/struct.Container.html

Demonstrates how to delete a container. Ensure the container is built and initialized before calling delete.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.delete(true)?;
```

--------------------------------

### Setup Container Scheduler

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/init/process.rs.html

Applies the specified scheduler settings to the container process. This is crucial for resource management.

```rust
setup_scheduler(ctx.process.scheduler())?;
```

--------------------------------

### Mount::setup_mount

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/rootfs/struct.Mount.html

Sets up a filesystem mount according to the provided specification and options.

```APIDOC
## Mount::setup_mount

### Description
Sets up a filesystem mount according to the provided specification and options.

### Method
`setup_mount(&self, mount: &SpecMount, options: &MountOptions<'_>) -> Result<(), MountError>`

### Parameters
#### Path Parameters
- `mount` (*SpecMount): The specification for the mount to be set up.
- `options` (*MountOptions): Options for the mount setup.

### Returns
- `Result<(), MountError>`: Returns Ok on success, or a MountError on failure.
```

--------------------------------

### Kill Container Process Example

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/struct.Container.html

Demonstrates sending a signal to the container's init process. The `all` parameter determines if the signal is sent to all processes.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;
use nix::sys::signal::Signal;

let mut container = ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.build()?;

container.kill(Signal::SIGKILL, false)?;
```

--------------------------------

### Symlink::setup_ptmx

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Sets up the /dev/ptmx symlink.

```APIDOC
## Symlink::setup_ptmx

### Description
Ensures the `/dev/ptmx` device is correctly set up as a symbolic link. It first attempts to remove any existing `/dev/ptmx` file before creating the symlink to `pts/ptmx`.

### Signature
```rust
pub fn setup_ptmx(&self, rootfs: &Path) -> Result<()>
```

### Parameters
- `rootfs`: A reference to the `Path` representing the root of the container's filesystem.

### Returns
A `Result` indicating success or a `SymlinkError` if the operation fails.
```

--------------------------------

### wait_for_move_network_device

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/process/channel/struct.InitReceiver.html

Waits for the network device move request and returns the associated CIDR addresses. This is used to get information about network interface movements during container setup.

```APIDOC
## wait_for_move_network_device

### Description
Waits for the network device move request and returns the associated CIDR addresses.

### Method
`&mut self`

### Returns
`Result<HashMap<String, Vec<CidrAddress>>, ChannelError>` - A HashMap where keys are interface names and values are vectors of CIDR addresses, or an error if communication fails.
```

--------------------------------

### LinkClient::set_up

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/network/link/struct.LinkClient.html

Sets a network interface to the up state.

```APIDOC
## LinkClient::set_up

### Description
Sets a network interface to the up state.

### Method
`pub fn set_up(&mut self, index: u32) -> Result<(), NetworkError>`

### Arguments
* `index` (u32) - The index of the network interface to modify.

### Returns
A `Result` indicating success or failure of the operation.
```

--------------------------------

### Setup Console After Pivot Root

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/tty.rs.html

This function is intended to be called after a pivot_root operation within the container. It outlines the initial steps for setting up the console, starting with creating a PTY pair from /dev/pts/ptmx.

```rust
/// Setup console AFTER pivot_root.
///
/// This function should be called AFTER pivot_root. This follows runc's approach:
/// setupConsole is called after pivotRoot in prepareRootfs.
///
/// The process:
/// 1. Create PTY pair from /dev/pts/ptmx (we're already in the container)

```

--------------------------------

### Setup /dev/ptmx Symlink

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Creates a symbolic link for /dev/ptmx. It first attempts to remove any existing file at this location before creating the symlink to 'pts/ptmx'.

```rust
    pub fn setup_ptmx(&self, rootfs: &Path) -> Result<()> {
        let ptmx = rootfs.join("dev/ptmx");
        if let Err(e) = remove_file(&ptmx) {
            if e.kind() != ::std::io::ErrorKind::NotFound {
                return Err(SymlinkError::Other {
                    msg: "could not delete /dev/ptmx".into(),
                });
            }
        }

        self.syscall
            .symlink(Path::new("pts/ptmx"), &ptmx)
            .map_err(|err| {
                tracing::error!("failed to symlink ptmx");
                SymlinkError::Syscall { source: err }
            })?;
        Ok(())
    }
```

--------------------------------

### Mount::setup_mount

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/mount.rs.html

Sets up a mount according to the OCI specification.

```APIDOC
## fn setup_mount(&self, mount: &SpecMount, options: &MountOptions) -> Result<()>

### Description
Performs the actual mount operation based on the provided `SpecMount` and `MountOptions`.

### Parameters
- **mount** (`&SpecMount`): The mount specification from the OCI runtime configuration.
- **options** (`&MountOptions`): Configuration options for the mount operation.

### Returns
- `Result<()>`: Ok(()) on success, or a `MountError` on failure.
```

--------------------------------

### Validate Method Signature

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/workload/trait.Executor.html

The `validate` method is required by the Executor trait to validate if a given `Spec` can be executed by the executor. This validation occurs after namespace and cgroup setup but before the container start signal.

```rust
fn validate(&self, spec: &Spec) -> Result<(), ExecutorValidationError>;
```

--------------------------------

### Run Create Container Hooks

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/init/process.rs.html

Executes the 'create_container' hooks after namespace setup and before pivot_root. These hooks run within the container's namespaces.

```rust
hooks::run_hooks(
                hooks.create_container().as_ref(),
                ctx.container.map(|c| &c.state),
                None,
                None,
            )
            .map_err(|err| {
                tracing::error!(?err, "failed to run create container hooks");
                InitProcessError::Hooks(err)
            })?;
```

--------------------------------

### setup_console

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/tty.rs.html

Sets up the console for a container by creating a pseudo-terminal (PTY), optionally mounting the PTY slave, sending the PTY master to a console socket, setting the controlling terminal, and connecting stdio to the PTY slave.

```APIDOC
## setup_console

### Description
Sets up the console for a container. This involves creating a pseudo-terminal (PTY), optionally mounting the PTY slave to `/dev/console`, sending the PTY master to a console socket, setting the controlling terminal, and connecting the container's standard input, output, and error streams to the PTY slave.

### Arguments
* `syscall` - A trait object implementing the `Syscall` trait for system calls.
* `console_fd` - The file descriptor for the console socket.
* `mount` - A boolean indicating whether to mount the PTY slave on `/dev/console`. This is typically `true` for the init process and `false` for exec processes.

### Returns
* `Ok(())` on success.
* `Err(TTYError)` on failure, with specific error variants for different stages of the setup process (e.g., `CreatePseudoTerminal`, `SendPtyMaster`, `MountConsole`, `CloseConsoleSocket`).
```

--------------------------------

### Notify Container Start

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/notify_socket/struct.NotifySocket.html

Sends a notification to start a container.

```APIDOC
## pub fn notify_container_start(&mut self) -> Result<(), NotifyListenerError>

### Description
Notifies that a container has started.

### Method
`&mut self`

### Returns
`Result<(), NotifyListenerError>`: Ok if the notification was sent successfully, or an error if it failed.
```

--------------------------------

### Symlink::setup_default_symlinks

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Sets up standard default symlinks in the rootfs.

```APIDOC
## Symlink::setup_default_symlinks

### Description
Creates a set of default symbolic links within the container's root filesystem. These typically include links for standard file descriptors like `/dev/fd`, `/dev/stdin`, `/dev/stdout`, and `/dev/stderr`.

### Signature
```rust
pub fn setup_default_symlinks(&self, rootfs: &Path) -> Result<()>
```

### Parameters
- `rootfs`: A reference to the `Path` representing the root of the container's filesystem.

### Returns
A `Result` indicating success or a `SymlinkError` if any of the symlink operations fail.
```

--------------------------------

### Check if Container Can Start

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/state/enum.ContainerStatus.html

Determines if a container is in a state where it can be started.

```rust
pub fn can_start(&self) -> bool
```

--------------------------------

### Symlink::setup_kcore_symlink

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Sets up the /dev/kcore symlink if /proc/kcore exists.

```APIDOC
## Symlink::setup_kcore_symlink

### Description
Creates a symbolic link for `/dev/kcore` pointing to `/proc/kcore`, but only if `/proc/kcore` exists on the host system. This is often architecture-dependent.

### Signature
```rust
pub fn setup_kcore_symlink(&self, rootfs: &Path) -> Result<()>
```

### Parameters
- `rootfs`: A reference to the `Path` representing the root of the container's filesystem.

### Returns
A `Result` indicating success or a `SymlinkError` if the symlink operation fails.
```

--------------------------------

### setup_mount function

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/mount.rs.html

Initiates the mounting process for a given SpecMount configuration and options. It parses mount options and handles specific types like 'cgroup'.

```rust
pub fn setup_mount(&self, mount: &SpecMount, options: &MountOptions) -> Result<()> {
    tracing::debug!("mounting {:?}", mount);
    let mut mount_option_config = parse_mount(mount)?;

    match mount.typ().as_deref() {
        Some("cgroup") => {
            let cgroup_setup = libcgroups::common::get_cgroup_setup().map_err(|err| {
                tracing::error!("failed to determine cgroup setup: {}", err);
                MountError::Other(err.into())
            })?;
            match cgroup_setup {
                Legacy | Hybrid => {
                    #[cfg(not(feature = "v1"))]

```

--------------------------------

### Notify Container Start Event

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/notify_socket/struct.NotifySocket.html

Sends a notification that a container has started. Returns a Result indicating success or a NotifyListenerError.

```rust
pub fn notify_container_start(&mut self) -> Result<(), NotifyListenerError>
```

--------------------------------

### Wait for Network Setup Ready

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/process/channel/struct.MainReceiver.html

Waits for the network setup to be ready. This is a signal indicating that network configurations have been applied.

```rust
pub fn wait_for_network_setup_ready(&mut self) -> Result<(), ChannelError>
```

--------------------------------

### Setup TTY Socket

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/tenant_builder.rs.html

Sets up a TTY socket for a container. It generates a unique name for the socket file and creates it if a console socket is specified.

```rust
fn setup_tty_socket(&self, container_dir: &Path) -> Result<Option<OwnedFd>, LibcontainerError> {
        let tty_name = Self::generate_name(container_dir, TENANT_TTY);
        let csocketfd = if let Some(console_socket) = &self.base.console_socket {
            Some(tty::setup_console_socket(
                container_dir,
                console_socket,
                &tty_name,
            )?) 
        } else {
            None
        };

        Ok(csocketfd)
    }
```

--------------------------------

### Configure ContainerBuilder with Options

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/builder.rs.html

Demonstrates chaining methods to configure root path, PID file, and console socket for a ContainerBuilder. The `as_init` method is used to prepare for building an init container.

```rust
use libcontainer::container::builder::ContainerBuilder;
use libcontainer::syscall::syscall::SyscallType;

ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.with_root_path("/run/containers/youki").expect("invalid root path")
.with_pid_file(Some("/var/run/docker.pid")).expect("invalid pid file")
.with_console_socket(Some("/var/run/docker/sock.tty"))
.as_init("/var/run/docker/bundle")
.build();

```

--------------------------------

### Symlink::setup_comount_symlinks

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Sets up symlinks for comounted subsystems.

```APIDOC
## Symlink::setup_comount_symlinks

### Description
Creates symbolic links for subsystems that have been comounted. This is useful when multiple cgroup controllers are mounted under a single path, and symlinks are needed to point to the correct controller.

### Signature
```rust
#[cfg(feature = "v1")]
pub fn setup_comount_symlinks(&self, cgroup_root: &Path, subsystem_name: &str) -> Result<()>
```

### Parameters
- `cgroup_root`: A reference to the `Path` representing the root of the cgroup filesystem.
- `subsystem_name`: A string slice representing the name of the subsystem, potentially containing comma-separated names if comounted.

### Returns
A `Result` indicating success or a `SymlinkError` if any symlink operation fails.
```

--------------------------------

### Test Network Setup Ready Signal

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/channel.rs.html

Tests the signaling mechanism for network setup readiness between parent and child processes using a channel.

```rust
let (sender, receiver) = &mut main_channel()?;
        match unsafe { unistd::fork()? } {
            unistd::ForkResult::Parent { child } => {
                wait::waitpid(child, None)?;
                receiver.wait_for_network_setup_ready()?;
                receiver.close()?;
            }
            unistd::ForkResult::Child => {
                sender
                    .network_setup_ready()
                    .with_context(|| "Failed to send network setup ready")?;
                sender.close()?;
                std::process::exit(0);
            }
        };
```

--------------------------------

### Run Container Setup

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/builder_impl.rs.html

Sets up the necessary components for running a container, including cgroup configuration and the notify socket. This function prepares the environment before the container process is executed.

```rust
fn run_container(&mut self) -> Result<Pid, LibcontainerError> {
        let linux = self.spec.linux().as_ref().ok_or(MissingSpecError::Linux)?;
        let cgroups_path = utils::get_cgroup_path(linux.cgroups_path(), &self.container_id);
        let cgroup_config = libcgroups::common::CgroupConfig {
            cgroup_path: cgroups_path,
            systemd_cgroup: self.use_systemd || self.user_ns_config.is_some(),
            container_name: self.container_id.to_owned(),
        };
        let process = self
            .spec
            .process()
            .as_ref()
            .ok_or(MissingSpecError::Process)?;

        // Need to create the notify socket before we pivot root, since the unix
        // domain socket used here is outside of the rootfs of container. During
        // exec, need to create the socket before we enter into existing mount
        // namespace. We also need to create to socket before entering into the
        // user namespace in the case that the path is located in paths only
        // root can access.
        let notify_listener = NotifyListener::new(&self.notify_path)?;

        // If Out-of-memory score adjustment is set in specification.  set the score
        // value for the current process check
        // https://dev.to/rrampage/surviving-the-linux-oom-killer-2ki9 for some more
        // information.
        //
        // This has to be done before !dumpable because /proc/self/oom_score_adj
        // is not writeable unless you're an privileged user (if !dumpable is

```

--------------------------------

### Setup Network Namespace and Addresses

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/process/init/process.rs.html

Initializes network clients, retrieves a network device by name, and sets up IP addresses for it within the specified network namespace. This is crucial for configuring network interfaces for containers.

```rust
let mut link_client = LinkClient::new(create_network_client()).map_err(|err| {
                tracing::error!(?err, "failed to create link client");
                err
            })?;
            let mut addr_client = AddressClient::new(create_network_client()).map_err(|err| {
                tracing::error!(?err, "failed to create address client");
                err
            })?;

            // Get the device index
            let ns_link = link_client.get_by_name(new_name).map_err(|err| {
                tracing::error!(?err, "failed to get device by name: {}", new_name);
                err
            })?;

            // Assign IP addresses to the device
            setup_addresses_in_network_namespace(
                cidr_addrs,
                ns_link.header.index,
                new_name,
                &mut addr_client,
            )
            .map_err(|err| {
                tracing::error!(?err, "failed to setup addresses for device: {}", new_name);
                err
            })?;

            // Bring the device up
            link_client.set_up(ns_link.header.index).map_err(|err| {
                tracing::error!(?err, "failed to bring up device: {}", new_name);
                err
            })?;
```

--------------------------------

### Setup Default Symlinks

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/symlink.rs.html

Creates standard symbolic links for file descriptors (stdin, stdout, stderr) and the process's file descriptor directory.

```rust
    pub fn setup_default_symlinks(&self, rootfs: &Path) -> Result<()> {
        let defaults = [
            ("/proc/self/fd", "dev/fd"),
            ("/proc/self/fd/0", "dev/stdin"),
            ("/proc/self/fd/1", "dev/stdout"),
            ("/proc/self/fd/2", "dev/stderr"),
        ];
        for (src, dst) in defaults {
            self.syscall
                .symlink(Path::new(src), &rootfs.join(dst))
                .map_err(|err| {
                    tracing::error!("failed to symlink defaults");
                    SymlinkError::Syscall { source: err }
                })?;
        }

        Ok(())
    }
```

--------------------------------

### Setup Emulated Cgroup Subsystem (v1)

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/mount.rs.html

Sets up an emulated cgroup subsystem for cgroup v1. It constructs a bind mount for the cgroup hierarchy and mounts it into the container, handling path joining and potential errors.

```rust
let named_hierarchy: Cow<str> = if named {
            format!("name={}", subsystem_name).into()
        } else {
            subsystem_name.into()
        };

        if let Some(proc_path) = process_cgroups.get(named_hierarchy.as_ref()) {
            let emulated = SpecMountBuilder::default()
                .source(
                    host_mount
                        .join_safely(proc_path.as_str())
                        .map_err(|err| {
                            tracing::error!(
                                "failed to join mount source for {} subsystem: {}",
                                subsystem_name,
                                err
                            );
                            MountError::Other(err.into())
                        })?,
                )
                .destination(
                    cgroup_mount
                        .destination()
                        .join_safely(subsystem_name)
                        .map_err(|err| {
                            tracing::error!(
                                "failed to join mount destination for {} subsystem: {}",
                                subsystem_name,
                                err
                            );
                            MountError::Other(err.into())
                        })?,
                )
                .typ("bind")
                .options(
                    ["rw", "rbind"]
                        .iter()
                        .map(|o| o.to_string())
                        .collect::<Vec<String>>(),
                )
                .build()?;
            tracing::debug!("Mounting emulated cgroup subsystem: {:?}", emulated);

            self.setup_mount(&emulated, options).map_err(|err| {
                tracing::error!("failed to mount {} cgroup hierarchy: {}", subsystem_name, err);
                err
            })?;
        } else {
            tracing::warn!("Could not mount {:?} cgroup subsystem", subsystem_name);
        }

        Ok(())
    }
```

--------------------------------

### Test Link Client Set Up Success

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/network/link.rs.html

Tests the successful execution of LinkClient::set_up, verifying the correct Netlink message is sent and acknowledged.

```rust
fn test_link_client_set_up_success() {
        let mut fake_client = FakeNetlinkClient::new();

        // Set up a successful response (ACK with code 0)
        let mut error_msg = netlink_packet_core::ErrorMessage::default();
        error_msg.code = std::num::NonZeroI32::new(0);
        let responses = vec![RouteNetlinkMessage::NewLink(LinkMessage::default())];
        fake_client.set_expected_responses(responses);

        let client_wrapper = ClientWrapper::Fake(fake_client);
        let mut link_client = LinkClient::new(client_wrapper).unwrap();

        let result = link_client.set_up(42);
        assert!(result.is_ok());

        // Verify the call was tracked
        if let ClientWrapper::Fake(fake_client) = &mut link_client.client {
            let send_calls = fake_client.get_send_calls();
            assert_eq!(send_calls.len(), 1);

            // Verify the message details
            if let NetlinkPayload::InnerMessage(RouteNetlinkMessage::SetLink(link)) = 
                &send_calls[0].payload
            {
                assert_eq!(link.header.index, 42);
                assert!(link.header.flags.contains(LinkFlags::Up));
                assert!(link.header.change_mask.contains(LinkFlags::Up));
            } else {
                panic!("Expected SetLink message");
            }

            // Verify the netlink flags
            let expected_flags = NLM_F_REQUEST | NLM_F_ACK;
            assert_eq!(send_calls[0].header.flags, expected_flags);
        } else {
            panic!("Expected Fake client");
        }
    }
```

--------------------------------

### as_init

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/builder.rs.html

Transforms this builder into an init builder, specifying the bundle path.

```APIDOC
## as_init

### Description
Transforms this builder into an init builder.

### Method
`as_init<P: Into<PathBuf>>(bundle: P)`

### Parameters
#### Path Parameters
- **bundle** (P) - Required - The path to the bundle directory.

### Example
```no_run
# use libcontainer::container::builder::ContainerBuilder;
# use libcontainer::syscall::syscall::SyscallType;

ContainerBuilder::new(
    "74f1a4cb3801".to_owned(),
    SyscallType::default(),
)
.as_init("/var/run/docker/bundle")
.with_systemd(false)
.build();
```
```

--------------------------------

### Get user home directory by UID

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/utils.rs.html

Fetches the home directory path for a given user ID. It first attempts to get the user's information and then returns their home directory if available.

```rust
pub fn get_user_home(uid: u32) -> Option<PathBuf> {
    match get_unix_user(Uid::from_raw(uid)) {

```

--------------------------------

### setup_console

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/tty/fn.setup_console.html

Sets up the console after pivot_root. This function should be called after pivot_root and follows runc's approach. It creates a PTY pair, optionally mounts the PTY slave, sends the PTY master to the console socket, sets the controlling terminal, and connects stdio to the PTY slave. This is crucial for CRIU checkpointing as it ensures the PTY belongs to a mount within the container's namespace.

```APIDOC
## Function: setup_console

### Description
Setup console AFTER pivot_root. This function should be called AFTER pivot_root. This follows runc’s approach: setupConsole is called after pivotRoot in prepareRootfs.

The process:
  1. Create PTY pair from /dev/pts/ptmx (we’re already in the container)
  2. Optionally mount PTY slave on /dev/console (bind mount) - only for init
  3. Send PTY master to console socket
  4. Set controlling terminal
  5. Connect stdio to PTY slave

By creating PTY from container’s devpts, the PTY belongs to a mount that exists within the container’s namespace, which is required for CRIU checkpoint.
See: https://github.com/opencontainers/runc/blob/v1.4.0/libcontainer/rootfs_linux.go

### Arguments
* `syscall` - A trait object implementing the Syscall trait.
* `console_fd` - The console socket file descriptor.
* `mount` - Whether to mount PTY slave on /dev/console (true for init, false for exec).

### Returns
* `Result<(), TTYError>` - Ok(()) on success, or a TTYError on failure.
```

--------------------------------

### get

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/namespaces/struct.Namespaces.html

Retrieves a specific namespace.

```APIDOC
### pub fn get( &self, k: LinuxNamespaceType, ) -> Result<Option<&LinuxNamespace>, NamespaceError>

Retrieves a specific namespace.
```

--------------------------------

### Container::can_start

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/container/struct.Container.html

Checks if the container can be started.

```APIDOC
## pub fn can_start

### Description
Checks if the container can be started.

### Returns
- `bool` - True if the container can be started, false otherwise.
```

--------------------------------

### Prepare Root Filesystem

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/rootfs/rootfs.rs.html

Prepares the container's root filesystem by mounting it, setting up necessary symlinks, creating devices, and setting up ptmx. This function orchestrates several other rootfs operations.

```rust
pub fn prepare_rootfs(
        &self,
        spec: &Spec,
        rootfs: &Path,
        bind_devices: bool,
        cgroup_ns: bool,
    ) -> Result<()> {
        tracing::debug!(?rootfs, "prepare rootfs");
        let linux = spec.linux().as_ref().ok_or(MissingSpecError::Linux)?;

        self.mount_to_rootfs(linux, spec, rootfs, cgroup_ns)?;

        let symlinker = Symlink::new();
        symlinker.setup_kcore_symlink(rootfs)?;
        symlinker.setup_default_symlinks(rootfs)?;

        let devicer = Device::new();
        if let Some(added_devices) = linux.devices() {
            let mut path_set = HashSet::new();
            let devices = default_devices();
            added_devices.iter().for_each(|d| {
                path_set.insert(d.path());
            });
            let default = devices.iter().filter(|d| !path_set.contains(d.path()));
            devicer.create_devices(rootfs, added_devices.iter().chain(default), bind_devices)
        } else {
            devicer.create_devices(rootfs, &default_devices(), bind_devices)
        }?; 

        symlinker.setup_ptmx(rootfs)?;
        Ok(())
    }
```

--------------------------------

### setup_intel_rdt

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/process/intel_rdt/fn.setup_intel_rdt.html

Sets up Intel RDT configuration for the container process based on the OCI config. The result bool tells whether or not we need to clean up the created subdirectory.

```APIDOC
## Function setup_intel_rdt

### Description
Sets up Intel RDT configuration for the container process based on the OCI config. The result bool tells whether or not we need to clean up the created subdirectory.

### Signature
```rust
pub fn setup_intel_rdt(
    maybe_container_id: Option<&str>,
    init_pid: &Pid,
    intel_rdt: &LinuxIntelRdt,
) -> Result<bool, IntelRdtError>
```

### Parameters
* `maybe_container_id` (Option<&str>): An optional container identifier.
* `init_pid` (&Pid): The process ID of the container's init process.
* `intel_rdt` (&LinuxIntelRdt): The Intel RDT configuration.

### Returns
* `Result<bool, IntelRdtError>`: Returns `Ok(true)` if cleanup is needed, `Ok(false)` if no cleanup is needed, or an `Err` if an IntelRdtError occurred.
```

--------------------------------

### setup_console_socket

Source: https://docs.rs/libcontainer/0.6.0/libcontainer/tty/fn.setup_console_socket.html

Sets up a console socket for a container, returning an owned file descriptor to the socket.

```APIDOC
## setup_console_socket

### Description
Sets up a console socket for a container. This function takes the container directory, the desired path for the console socket, and a name for the socket as input. It returns an `OwnedFd` representing the file descriptor of the created socket or a `TTYError` if the operation fails.

### Signature
```rust
pub fn setup_console_socket(
    container_dir: &Path,
    console_socket_path: &Path,
    socket_name: &str,
) -> Result<OwnedFd, TTYError>
```

### Parameters

*   `container_dir` (*Path*) - The directory of the container.
*   `console_socket_path` (*Path*) - The path where the console socket will be created.
*   `socket_name` (*str*) - The name of the console socket file.

### Returns

*   `Result<OwnedFd, TTYError>` - An `Ok` containing an `OwnedFd` of the console socket on success, or an `Err` containing a `TTYError` on failure.
```

--------------------------------

### Get container ID

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container.rs.html

Returns the unique identifier for the container.

```rust
pub fn id(&self) -> &str {
        &self.state.id
    }
```

--------------------------------

### get_executor Function

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/workload/default.rs.html

Provides a factory function to get an instance of the DefaultExecutor.

```rust
pub fn get_executor() -> Box<dyn Executor> {
    Box::new(DefaultExecutor {})
}
```

--------------------------------

### Configuring a filesystem with `fsconfig`

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/syscall/linux.rs.html

This function configures an opened filesystem. It takes a file descriptor for the filesystem, a command, and optional key-value pairs for configuration. The `aux` parameter can be used for additional arguments.

```rust
fn fsconfig(
        &self,
        fsfd: BorrowedFd<'_>,
        cmd: u32,
        key: Option<&str>,
        val: Option<&str>,
        aux: libc::c_int,
    ) -> Result<()> {
        let k_cstr: Option<CString> = key
            .map(|k| CString::new(k).map_err(|_| SyscallError::Nix(nix::errno::Errno::EINVAL)))
            .transpose()?;
        let k_ptr = k_cstr.as_ref().map_or(std::ptr::null(), |k| k.as_ptr());

        let v_cstr: Option<CString> = val

```

--------------------------------

### Get current container status

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container.rs.html

Returns the current status of the container.

```rust
pub fn status(&self) -> ContainerStatus {
        self.state.status
    }
```

--------------------------------

### Get container creation time

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container.rs.html

Returns the timestamp when the container was created, if available.

```rust
pub fn created(&self) -> Option<DateTime<Utc>> {
        self.state.created
    }
```

--------------------------------

### File I/O Operations

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/utils.rs.html

Demonstrates basic file I/O operations including writing, opening, and creating directories. Shows error handling for invalid operations.

```rust
{ 
    let tempdir = tempfile::tempdir()?;
    let path = tempdir.path().join("test");
    write_file(&path, "test".as_bytes())?;
    open(&path)?;
    assert!(create_dir_all(path).is_err());
}
{
    let tempdir = tempfile::tempdir()?;
    let path = tempdir.path().join("test");
    create_dir_all(&path)?;
    assert!(write_file(&path, "test".as_bytes()).is_err());
}
{
    let tempdir = tempfile::tempdir()?;
    let path = tempdir.path().join("test");
    assert!(open(&path).is_err());
    create_dir_all(&path)?;
    assert!(path.is_dir())
}
```

--------------------------------

### Get container bundle path

Source: https://docs.rs/libcontainer/0.6.0/src/libcontainer/container/container.rs.html

Returns a reference to the container's bundle path.

```rust
pub fn bundle(&self) -> &PathBuf {
        &self.state.bundle
    }
```
Tokens:
Raw