Module storage 

Storage access for container overlay filesystem.

This module provides the main Storage struct for accessing containers-storage overlay driver data. All file access uses cap-std for fd-relative operations, providing security against path traversal attacks and TOCTOU race conditions.

Overview

The Storage struct is the primary entry point for interacting with container storage. It holds a capability-based directory handle to the storage root.

Storage Structure

Container storage on disk follows this layout:

/var/lib/containers/storage/
+-- overlay/            # Layer data
|   +-- <layer-id>/     # Individual layer directories
|   |   +-- diff/       # Layer file contents
|   |   +-- link        # Short link ID (26 chars)
|   |   +-- lower       # Parent layer references
|   +-- l/              # Short link directory (symlinks)
+-- overlay-layers/     # Tar-split metadata
|   +-- <layer-id>.tar-split.gz
+-- overlay-images/     # Image metadata
    +-- <image-id>/
        +-- manifest    # OCI image manifest
        +-- =<key>      # Base64-encoded metadata files

Security Model

All file operations are performed via cap_std::fs::Dir handles, which provide:

• Protection against path traversal attacks
• Prevention of TOCTOU race conditions
• Guarantee that all access stays within the storage directory tree

Structs

LayerMetadata

Metadata about a layer from layers.json.

Storage

Main storage handle providing read-only access to container storage.