Crate composefs_storage 

Read-only access to containers-storage overlay driver.

This library provides efficient, capability-based access to container image storage using the overlay driver. All file operations are performed using file descriptor-relative operations via cap-std, providing security against path traversal attacks and TOCTOU race conditions.

Overview

The library is designed to access containers-storage (overlay driver) without requiring tar serialization. Instead, it provides direct file descriptor access to layer content, enabling zero-copy operations.

Key Features

• Capability-based security: All file access via cap_std::fs::Dir handles
• Zero-copy access: File descriptors instead of data copies
• Safe by design: No path traversal vulnerabilities
• Tar-split integration: Bit-for-bit identical TAR reconstruction
• OCI compatibility: Uses oci-spec for standard image formats

Example

use composefs_storage::Storage;

// Discover storage from default locations
let storage = Storage::discover()?;

// Or open storage at a specific path
let storage = Storage::open("/var/lib/containers/storage")?;

// List images
for image in storage.list_images()? {
    println!("Image: {}", image.id());
}

Architecture

The library uses cap-std for all file operations:

• Storage holds a Dir handle to the storage root
• All file access is relative to Dir handles
• No absolute paths are constructed during operations
• SQLite database accessed via fd-relative path

Re-exports

pub use config::AdditionalLayerStore;

pub use config::StorageConfig;

pub use error::Result;

pub use error::StorageError;

pub use image::Image;

pub use layer::Layer;

pub use storage::LayerMetadata;

pub use storage::Storage;

pub use tar_split::TarHeader;

pub use tar_split::TarSplitFdStream;

pub use tar_split::TarSplitItem;

pub use userns::can_bypass_file_permissions;

Modules

config

Configuration parsing for container storage.

error

Error types for the cstorage library.

image

Image reading and manifest parsing.

layer

Layer reading and metadata handling.

storage

Storage access for container overlay filesystem.

tar_split

Tar-split integration for reading container layers without full tar serialization.

userns

User namespace utilities for rootless containers-storage access.

Structs

Descriptor

A Content Descriptor (or simply Descriptor) describes the disposition of the targeted content. It includes the type of the content, a content identifier (digest), and the byte-size of the raw content. Descriptors SHOULD be embedded in other formats to securely reference external content.

ImageConfiguration

The image configuration is associated with an image and describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.

ImageManifest

Unlike the image index, which contains information about a set of images that can span a variety of architectures and operating systems, an image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.