apt-ostree/.notes/ostree/rpm-ostree.md

rpm-ostree OSTree Implementation

Overview

rpm-ostree integrates OSTree as its core filesystem management system, providing atomic, immutable deployments with RPM package layering capabilities. This document explains how rpm-ostree implements and extends OSTree functionality.

Core OSTree Integration

Repository Management

rpm-ostree maintains an OSTree repository at /ostree/repo that stores:

• Content-addressable objects: Files and metadata stored by SHA256 hash
• Commits: Immutable snapshots of filesystem trees
• Refs: Symbolic pointers to specific commits (e.g., fedora/39/x86_64/silverblue)
• Static deltas: Pre-calculated differences between commits for efficient updates

Deployment Structure

/ostree/
├── repo/                      # OSTree repository (content-addressable storage)
├── deploy/                    # Active deployments
│   └── fedora-silverblue/     # State root for Fedora Silverblue
│       ├── var/               # Shared mutable data across deployments
│       └── <checksum>/        # Individual deployment directories
└── boot/                      # Bootloader configuration

Filesystem Assembly

rpm-ostree assembles the live filesystem using:

• Hardlinks: Deployments use hardlinks to objects in /ostree/repo
• Bind mounts: Read-only /usr mounted from deployment
• Symlinks: User directories redirected to /var
• 3-way merge: /etc merged from old deployment, new deployment, and local changes

RPM-OSTree Specific Extensions

Package Layering

rpm-ostree extends OSTree with RPM package layering:

// Core layering implementation in rpmostree-core.cxx
class RpmOstreeCore {
    // Create new deployment with layered packages
    gboolean create_deployment_with_layers(
        RpmOstreeSysroot *sysroot,
        const char *base_commit,
        const char *new_commit,
        GPtrArray *layered_packages,
        GCancellable *cancellable,
        GError **error);
    
    // Apply package layers to deployment
    gboolean apply_package_layers(
        RpmOstreeSysroot *sysroot,
        const char *deployment_path,
        GPtrArray *packages,
        GCancellable *cancellable,
        GError **error);
};

Transaction Management

rpm-ostree implements atomic transactions for all OSTree operations:

// Transaction types for OSTree operations
typedef enum {
    RPMOSTREE_TRANSACTION_TYPE_DEPLOY,
    RPMOSTREE_TRANSACTION_TYPE_ROLLBACK,
    RPMOSTREE_TRANSACTION_TYPE_PKG_CHANGE,
    RPMOSTREE_TRANSACTION_TYPE_REBASE,
    RPMOSTREE_TRANSACTION_TYPE_UPGRADE
} RpmOstreeTransactionType;

// Transaction execution with OSTree integration
class RpmOstreeTransaction {
    // Execute transaction with OSTree commit creation
    gboolean execute_with_ostree_commit(
        RpmOstreeSysroot *sysroot,
        const char *base_commit,
        const char *new_commit,
        GCancellable *cancellable,
        GError **error);
    
    // Rollback to previous OSTree deployment
    gboolean rollback_to_previous_deployment(
        RpmOstreeSysroot *sysroot,
        GCancellable *cancellable,
        GError **error);
};

OSTree Commit Creation

rpm-ostree creates OSTree commits for all system changes:

// Commit creation workflow
gboolean rpmostree_create_commit(
    RpmOstreeSysroot *sysroot,
    const char *base_commit,
    const char *new_commit,
    const char *subject,
    GPtrArray *layered_packages,
    GCancellable *cancellable,
    GError **error) {
    
    // 1. Extract base filesystem from OSTree commit
    g_autoptr(OstreeRepo) repo = rpmostree_sysroot_get_repo(sysroot);
    g_autoptr(GFile) base_tree = ostree_repo_read_commit(repo, base_commit, NULL, NULL, error);
    
    // 2. Apply RPM package layers
    g_autoptr(GFile) layered_tree = apply_rpm_layers(base_tree, layered_packages, error);
    
    // 3. Create new OSTree commit
    g_autofree char *new_commit_checksum = ostree_repo_write_commit(
        repo, layered_tree, subject, NULL, NULL, error);
    
    // 4. Update ref to point to new commit
    ostree_repo_set_ref(repo, NULL, "fedora/39/x86_64/silverblue", new_commit_checksum, NULL, error);
    
    return TRUE;
}

OSTree Environment Detection

rpm-ostree detects OSTree environments using multiple methods:

// Environment detection in rpmostree-sysroot-core.cxx
gboolean rpmostree_sysroot_is_ostree(RpmOstreeSysroot *sysroot) {
    // Method 1: Check for /ostree directory
    if (!g_file_test("/ostree", G_FILE_TEST_IS_DIR))
        return FALSE;
    
    // Method 2: Check for /run/ostree-booted file
    if (!g_file_test("/run/ostree-booted", G_FILE_TEST_EXISTS))
        return FALSE;
    
    // Method 3: Check kernel command line for ostree parameter
    g_autofree char *cmdline = rpmostree_get_kernel_cmdline();
    if (!strstr(cmdline, "ostree"))
        return FALSE;
    
    // Method 4: Try to load OSTree sysroot
    g_autoptr(OstreeSysroot) ostree_sysroot = ostree_sysroot_new_default();
    return ostree_sysroot_load(ostree_sysroot, NULL, NULL);
}

OSTree Integration Points

Daemon Integration

The rpm-ostree daemon integrates with OSTree for privileged operations:

// Daemon OSTree operations in rpmostreed-os.cxx
class RpmOstreedOS {
    // OSTree deployment management
    gboolean deploy_ostree_commit(
        const char *commit_checksum,
        const char *osname,
        GCancellable *cancellable,
        GError **error);
    
    // OSTree rollback operations
    gboolean rollback_ostree_deployment(
        const char *osname,
        GCancellable *cancellable,
        GError **error);
    
    // OSTree status reporting
    gboolean get_ostree_status(
        GVariant **status,
        GCancellable *cancellable,
        GError **error);
};

CLI Integration

rpm-ostree CLI commands integrate with OSTree operations:

// CLI command integration in rpmostree-builtin-deploy.cxx
gboolean rpmostree_builtin_deploy(int argc, char **argv, RpmOstreeCommandInvocation *invocation, GCancellable *cancellable, GError **error) {
    // Parse command line arguments
    g_autoptr(GOptionContext) context = g_option_context_new("COMMIT");
    g_option_context_add_main_entries(context, entries, NULL);
    
    // Get OSTree commit to deploy
    const char *commit = argv[1];
    
    // Create deployment via D-Bus daemon
    g_autoptr(RpmOstreeClient) client = rpmostree_client_new();
    return rpmostree_client_deploy(client, commit, cancellable, error);
}

OSTree Performance Optimizations

Static Delta Support

rpm-ostree leverages OSTree static deltas for efficient updates:

// Static delta usage in rpmostree-core.cxx
gboolean rpmostree_pull_with_static_deltas(
    RpmOstreeSysroot *sysroot,
    const char *remote_name,
    const char *refspec,
    GCancellable *cancellable,
    GError **error) {
    
    // Configure static delta usage
    g_autoptr(OstreeRepo) repo = rpmostree_sysroot_get_repo(sysroot);
    ostree_repo_set_enable_static_deltas(repo, TRUE);
    
    // Pull with static delta optimization
    return ostree_repo_pull(repo, remote_name, refspec, NULL, cancellable, error);
}

Content Deduplication

rpm-ostree benefits from OSTree's content-addressable storage:

// Content deduplication example
gboolean rpmostree_commit_with_deduplication(
    RpmOstreeSysroot *sysroot,
    const char *base_commit,
    const char *new_commit,
    GCancellable *cancellable,
    GError **error) {
    
    // OSTree automatically deduplicates identical files
    // Only unique content is stored in the repository
    g_autoptr(OstreeRepo) repo = rpmostree_sysroot_get_repo(sysroot);
    
    // Create commit with automatic deduplication
    return ostree_repo_write_commit(repo, new_tree, subject, NULL, NULL, error);
}

OSTree Security Features

GPG Signature Verification

rpm-ostree verifies OSTree commits using GPG signatures:

// GPG verification in rpmostree-core.cxx
gboolean rpmostree_verify_commit_signature(
    RpmOstreeSysroot *sysroot,
    const char *commit_checksum,
    GCancellable *cancellable,
    GError **error) {
    
    g_autoptr(OstreeRepo) repo = rpmostree_sysroot_get_repo(sysroot);
    
    // Verify commit signature
    g_autoptr(OstreeSign) sign = ostree_sign_new();
    return ostree_repo_verify_commit(repo, commit_checksum, sign, cancellable, error);
}

Read-Only Filesystem Enforcement

rpm-ostree enforces OSTree's read-only filesystem model:

// Read-only enforcement in rpmostree-sysroot-core.cxx
gboolean rpmostree_enforce_readonly_filesystem(
    RpmOstreeSysroot *sysroot,
    GCancellable *cancellable,
    GError **error) {
    
    // Mount /usr as read-only
    g_autofree char *usr_mount = g_strdup_printf("mount --bind -o ro %s /usr", deployment_path);
    return rpmostree_sysroot_run_sync(sysroot, usr_mount, cancellable, error);
}

OSTree Integration Testing

Deployment Testing

# Test OSTree deployment creation
rpm-ostree deploy $(rpm-ostree status --json | jq -r '.deployments[0].checksum')

# Test OSTree rollback
rpm-ostree rollback

# Test OSTree status
rpm-ostree status --json

Performance Testing

# Test OSTree pull performance
time ostree pull fedora fedora/39/x86_64/silverblue

# Test static delta usage
ostree pull --enable-static-deltas fedora fedora/39/x86_64/silverblue

# Test commit creation performance
time rpm-ostree install package-name

OSTree Troubleshooting

Common Issues

1. OSTree repository corruption: Use ostree fsck to verify repository integrity
2. Deployment failures: Check /var/log/ostree.log for detailed error messages
3. Bootloader issues: Verify GRUB configuration with ostree admin boot
4. Space issues: Use ostree admin cleanup to remove old deployments

Debug Commands

# Check OSTree repository status
ostree fsck --repo=/ostree/repo

# List available deployments
ostree admin status

# Check bootloader configuration
ostree admin boot

# Verify commit signatures
ostree verify --repo=/ostree/repo fedora/39/x86_64/silverblue

OSTree Future Enhancements

Planned Features

1. Composefs Integration: Enhanced filesystem layering with composefs
2. OCI Container Support: Direct OSTree to OCI container conversion
3. Bootc Compatibility: Integration with bootc for container-native deployments
4. Enhanced Static Deltas: Improved delta generation and application

Integration Roadmap

• Phase 1: Core OSTree integration (✅ Complete)
• Phase 2: Performance optimizations (✅ Complete)
• Phase 3: Security enhancements (✅ Complete)
• Phase 4: OCI container support (🔄 In Progress)
• Phase 5: Bootc compatibility (📋 Planned)