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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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:

```c
// 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

```bash
# 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

```bash
# 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

```bash
# 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)