Struct MicroVmConfigBuilder

pub struct MicroVmConfigBuilder<R, E> { /* private fields */ }

The builder for a MicroVm configuration.

Required Fields

• rootfs: The root filesystem to use for the MicroVm.
• exec_path: The path to the executable to run in the MicroVm.

Optional Fields

• num_vcpus: The number of virtual CPUs to use for the MicroVm.
• memory_mib: The amount of memory in MiB to use for the MicroVm.
• mapped_dirs: The directories to mount in the MicroVm.
• port_map: The ports to map in the MicroVm.
• rlimits: The resource limits to use for the MicroVm.
• workdir_path: The working directory to use for the MicroVm.
• args: The arguments to pass to the executable.
• env: The environment variables to use for the MicroVm.
• console_output: The path to the file to write the console output to.

Implementations

impl<R, M> MicroVmConfigBuilder<R, M>

pub fn log_level(self, log_level: LogLevel) -> Self

Sets the log level for the MicroVm.

The log level controls the verbosity of the MicroVm’s logging output.

Examples

use microsandbox_core::vm::{MicroVmConfigBuilder, LogLevel};

let config = MicroVmConfigBuilder::default()
    .log_level(LogLevel::Debug);  // Enable debug logging

Log Levels

• Off - No logging (default)
• Error - Only error messages
• Warn - Warnings and errors
• Info - Informational messages, warnings, and errors
• Debug - Debug information and all above
• Trace - Detailed trace information and all above

pub fn rootfs(self, rootfs: Rootfs) -> MicroVmConfigBuilder<Rootfs, M>

Sets the root filesystem sharing mode for the MicroVm.

This determines how the root filesystem is shared with the guest system, with two options:

• Rootfs::Native: Direct passthrough of a directory as the root filesystem
• Rootfs::Overlayfs: Use overlayfs with multiple layers as the root filesystem

Examples

use microsandbox_core::vm::{MicroVmConfigBuilder, Rootfs};
use std::path::PathBuf;

let config = MicroVmConfigBuilder::default()
    // Option 1: Direct passthrough of a directory
    .rootfs(Rootfs::Native(PathBuf::from("/path/to/rootfs")));

let config = MicroVmConfigBuilder::default()
    // Option 2: Overlayfs with multiple layers
    .rootfs(Rootfs::Overlayfs(vec![
        PathBuf::from("/path/to/layer1"),
        PathBuf::from("/path/to/layer2")
    ]));

Notes

• For Passthrough: The directory must exist and contain a valid root filesystem structure
• For Overlayfs: The layers are stacked in order, with later layers taking precedence
• Common choices include Alpine Linux or Ubuntu root filesystems

pub fn num_vcpus(self, num_vcpus: u8) -> Self

Sets the number of virtual CPUs (vCPUs) for the MicroVm.

This determines how many CPU cores are available to the guest system.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .num_vcpus(2);  // Allocate 2 virtual CPU cores

Notes

• The default is 1 vCPU if not specified
• The number of vCPUs should not exceed the host’s physical CPU cores
• More vCPUs aren’t always better - consider the workload’s needs

pub fn memory_mib(self, memory_mib: u32) -> Self

Sets the amount of memory in MiB for the MicroVm.

This determines how much memory is available to the guest system.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .memory_mib(1024);  // Allocate 1 GiB of memory

Notes

• The value is in MiB (1 GiB = 1024 MiB)
• Consider the host’s available memory when setting this value
• Common values: 512 MiB for minimal systems, 1024-2048 MiB for typical workloads

pub fn mapped_dirs( self, mapped_dirs: impl IntoIterator<Item = PathPair>, ) -> Self

Sets the directory mappings for the MicroVm using virtio-fs.

Each mapping follows Docker’s volume mapping convention using the format host:guest.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .mapped_dirs([
        // Share host's /data directory as /mnt/data in guest
        "/data:/mnt/data".parse()?,
        // Share current directory as /app in guest
        "./:/app".parse()?,
        // Use same path in both host and guest
        "/shared".parse()?
    ]);

Notes

• Host paths must exist and be accessible
• Guest paths will be created if they don’t exist
• Changes in shared directories are immediately visible to both systems
• Useful for development, configuration files, and data sharing

pub fn port_map(self, port_map: impl IntoIterator<Item = PortPair>) -> Self

Sets the port mappings between host and guest for the MicroVm.

Port mappings follow Docker’s convention using the format host:guest, where:

• host is the port number on the host machine
• guest is the port number inside the MicroVm

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;
use microsandbox_core::config::PortPair;

let config = MicroVmConfigBuilder::default()
    .port_map([
        // Map host port 8080 to guest port 80
        "8080:80".parse()?,
        // Map host port 2222 to guest port 22
        "2222:22".parse()?,
        // Use same port (3000) on both host and guest
        "3000".parse()?
    ]);

Notes

• If you don’t call this method, no ports will be mapped between host and guest
• The guest application will need to use the guest port number to listen for connections
• External connections should use the host port number to connect to the service

pub fn scope(self, scope: NetworkScope) -> Self

Sets the network scope for the MicroVm.

The network scope controls the MicroVm’s level of network isolation and connectivity.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;
use microsandbox_core::config::NetworkScope;

let config = MicroVmConfigBuilder::default()
    .scope(NetworkScope::Public);  // Allow access to public networks

Network Scope Options

• None - Sandboxes cannot communicate with any other sandboxes
• Group - Sandboxes can only communicate within their subnet (default)
• Public - Sandboxes can communicate with any other non-private address
• Any - Sandboxes can communicate with any address

Notes

• Choose the appropriate scope based on your security requirements
• More restrictive scopes provide better isolation
• The default scope is Group if not specified

pub fn ip(self, ip: Ipv4Addr) -> Self

Sets the IP address for the MicroVm.

This sets a specific IPv4 address for the guest system’s network interface.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;
use std::net::Ipv4Addr;

let config = MicroVmConfigBuilder::default()
    .ip(Ipv4Addr::new(192, 168, 1, 100));  // Assign IP 192.168.1.100 to the MicroVm

Notes

• The IP address should be within the subnet assigned to the MicroVm
• If not specified, an IP address may be assigned automatically
• Useful for predictable addressing when running multiple MicroVms
• Consider using with the subnet method to define the network

pub fn subnet(self, subnet: Ipv4Network) -> Self

Sets the subnet for the MicroVm.

This defines the IPv4 network and mask for the guest system’s network interface.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;
use ipnetwork::Ipv4Network;

let config = MicroVmConfigBuilder::default()
    .subnet("192.168.1.0/24".parse()?);  // Set subnet to 192.168.1.0/24

Notes

• The subnet defines the range of IP addresses available to the MicroVm
• Common subnet masks: /24 (256 addresses), /16 (65536 addresses)
• IP addresses assigned to the MicroVm should be within this subnet
• Important for networking between multiple MicroVms in the same group

pub fn rlimits(self, rlimits: impl IntoIterator<Item = LinuxRlimit>) -> Self

Sets the resource limits for processes in the MicroVm.

Resource limits control various system resources available to processes running in the guest system, following Linux’s rlimit convention.

Format

Resource limits use the format RESOURCE=SOFT:HARD or NUMBER=SOFT:HARD, where:

• RESOURCE is the resource name (e.g., RLIMIT_NOFILE)
• NUMBER is the resource number (e.g., 7 for RLIMIT_NOFILE)
• SOFT is the soft limit (enforced limit)
• HARD is the hard limit (ceiling for soft limit)

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .rlimits([
        // Limit number of open files
        "RLIMIT_NOFILE=1024:2048".parse()?,
        // Limit process memory
        "RLIMIT_AS=1073741824:2147483648".parse()?,  // 1GB:2GB
        // Can also use resource numbers
        "7=1024:2048".parse()?  // Same as RLIMIT_NOFILE
    ]);

Common Resource Limits

• RLIMIT_NOFILE (7) - Maximum number of open files
• RLIMIT_AS (9) - Maximum size of process’s virtual memory
• RLIMIT_NPROC (6) - Maximum number of processes
• RLIMIT_CPU (0) - CPU time limit in seconds
• RLIMIT_FSIZE (1) - Maximum file size

pub fn workdir_path(self, workdir_path: impl Into<Utf8UnixPathBuf>) -> Self

Sets the working directory for processes in the MicroVm.

This directory will be the current working directory (cwd) for any processes started in the guest system.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .workdir_path("/app")  // Set working directory to /app
    .exec_path("/app/myapp")  // Run executable from /app
    .args(["--config", "config.json"]);  // Config file will be looked up in /app

Notes

• The path must be absolute
• The directory must exist in the guest filesystem
• Useful for applications that need to access files relative to their location

pub fn exec_path( self, exec_path: impl Into<Utf8UnixPathBuf>, ) -> MicroVmConfigBuilder<R, Utf8UnixPathBuf>

Sets the path to the executable to run in the MicroVm.

This specifies the program that will be executed when the MicroVm starts.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .exec_path("/usr/local/bin/nginx")  // Run nginx web server
    .args(["-c", "/etc/nginx/nginx.conf"]);  // With specific config

Notes

• The path must be absolute
• The executable must exist and be executable in the guest filesystem
• The path is relative to the guest’s root filesystem

pub fn args<'a>(self, args: impl IntoIterator<Item = &'a str>) -> Self

Sets the command-line arguments for the executable.

These arguments will be passed to the program specified by exec_path.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .exec_path("/usr/bin/python3")
    .args([
        "-m", "http.server",  // Run Python's HTTP server module
        "8080",               // Listen on port 8080
        "--directory", "/data" // Serve files from /data
    ]);

Notes

• Arguments are passed in the order they appear in the iterator
• The program name (argv[0]) is automatically set from exec_path
• Each argument should be a separate string

pub fn env(self, env: impl IntoIterator<Item = EnvPair>) -> Self

Sets environment variables for processes in the MicroVm.

Environment variables follow the standard format KEY=VALUE and are available to all processes in the guest system.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .env([
        // Set application environment
        "APP_ENV=production".parse()?,
        // Configure logging
        "LOG_LEVEL=info".parse()?,
        // Set timezone
        "TZ=UTC".parse()?,
        // Multiple values are OK
        "ALLOWED_HOSTS=localhost,127.0.0.1".parse()?
    ]);

Notes

• Variables are available to all processes in the guest
• Values should be properly escaped if they contain special characters
• Common uses include configuration and runtime settings
• Some programs expect specific environment variables to function

pub fn console_output(self, console_output: impl Into<Utf8UnixPathBuf>) -> Self

Sets the path for capturing console output from the MicroVm.

This allows redirecting and saving all console output (stdout/stderr) from the guest system to a file on the host.

Examples

use microsandbox_core::vm::MicroVmConfigBuilder;

let config = MicroVmConfigBuilder::default()
    .console_output("/var/log/microvm.log")  // Save output to log file
    .exec_path("/usr/local/bin/myapp");      // Run application

Notes

• The path must be writable on the host system
• The file will be created if it doesn’t exist
• Useful for debugging and logging
• Captures both stdout and stderr

impl MicroVmConfigBuilder<Rootfs, Utf8UnixPathBuf>

pub fn build(self) -> MicroVmConfig

Builds the MicroVm configuration.

Trait Implementations

impl<R: Debug, E: Debug> Debug for MicroVmConfigBuilder<R, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MicroVmConfigBuilder<(), ()>

fn default() -> Self

Returns the “default value” for a type.