apt-ostree/.notes/rpm-ostree-execution-model-summary.md

rpm-ostree Execution Model Summary

Date: December 19, 2024
Source: Analysis of .notes/inspiration/rpm-ostree-main source code

Key Finding: Execution Model Decision Logic

The execution model is determined by a simple flag check:

const RpmOstreeBuiltinFlags flags = invocation ? invocation->command->flags : RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD;
gboolean use_daemon = ((flags & RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD) == 0);

Rule: If LOCAL_CMD flag is set → runs locally. If not → uses daemon.

Command Classification

Daemon-Based Commands (15/21) - NO LOCAL_CMD flag

System Management:

• status - Get system version and deployment info
• upgrade - Perform a system upgrade
• rollback - Revert to previously booted tree
• deploy - Deploy a specific commit
• rebase - Switch to different tree
• reset - Remove all mutations
• apply-live - Apply pending deployment changes

Package Management:

• install - Overlay additional packages
• uninstall - Remove overlayed packages
• search - Search for packages

System Configuration:

• initramfs - Manage initramfs regeneration
• initramfs-etc - Add files to initramfs
• kargs - Query/modify kernel arguments
• cleanup - Clear cached/pending data
• reload - Reload configuration
• refresh-md - Generate rpm repo metadata
• cancel - Cancel active transaction
• finalize-deployment - Finalize deployment

Local Commands (6/21) - HAVE LOCAL_CMD flag

Compose System:

• compose - Commands to compose a tree (9 subcommands)
  • All subcommands have LOCAL_CMD flag
  • No daemon communication required
  • Direct OSTree and package operations

Database Operations:

• db - Commands to query RPM database (3 subcommands)
  • diff - Show package changes between commits
  • list - List packages within commits
  • version - Show rpmdb version

Package Overrides:

• override - Manage base package overrides
  • Direct package override operations
  • No daemon communication

Experimental/Internal:

• ex - Experimental commands (hidden)
• testutils - Testing utilities (hidden)
• shlib-backend - Shared library backend (hidden)
• start-daemon - Start daemon (hidden)

Daemon Communication Pattern

Connection Flow

// 1. Load sysroot proxy
g_autoptr(RPMOSTreeSysroot) sysroot_proxy = NULL;
if (!rpmostree_load_sysroot(opt_sysroot, cancellable, &sysroot_proxy, error))
  return FALSE;

// 2. Load OS proxy  
g_autoptr(RPMOSTreeOS) os_proxy = NULL;
if (!rpmostree_load_os_proxy(sysroot_proxy, opt_osname, cancellable, &os_proxy, error))
  return FALSE;

// 3. Execute operation via D-Bus
if (!rpmostree_os_call_method_sync(os_proxy, ...))
  return FALSE;

D-Bus Interface

#define BUS_NAME "org.projectatomic.rpmostree1"

Option Parsing Differences

Daemon-Based Commands Get:

• --sysroot - Use system root (default: /)
• --peer - Force peer-to-peer connection
• Package options (if SUPPORTS_PKG_INSTALLS):
  • --install - Overlay additional package
  • --uninstall - Remove overlayed package

Local Commands Get:

• Global options (--version, --quiet)
• Command-specific options
• No daemon-specific options

Command Flags

typedef enum {
  RPM_OSTREE_BUILTIN_FLAG_NONE = 0,
  RPM_OSTREE_BUILTIN_FLAG_LOCAL_CMD = 1 << 0,        // Run locally, no daemon
  RPM_OSTREE_BUILTIN_FLAG_REQUIRES_ROOT = 1 << 1,    // Requires root privileges
  RPM_OSTREE_BUILTIN_FLAG_HIDDEN = 1 << 2,           // Hidden from help
  RPM_OSTREE_BUILTIN_FLAG_SUPPORTS_PKG_INSTALLS = 1 << 3,  // Supports --install/--uninstall
  RPM_OSTREE_BUILTIN_FLAG_CONTAINER_CAPABLE = 1 << 4,      // Can run in containers
} RpmOstreeBuiltinFlags;

Key Insights for apt-ostree

1. Architecture Split is Clear

• 15 commands use daemon (system operations)
• 6 commands run locally (compose, db, override)
• Decision is binary: LOCAL_CMD flag determines execution model

2. Compose System is Fully Local

• All 9 compose subcommands have LOCAL_CMD flag
• No daemon communication required
• Perfect for container workflows and CI/CD

3. Package Operations Split

• System operations: install/uninstall/search via daemon
• Compose operations: install via local compose commands
• Database queries: db commands run locally

4. Privilege Separation

• Daemon handles: Privileged system operations
• Local handles: Development, debugging, container operations
• Security model: Clear separation of concerns

Implementation Strategy for apt-ostree

Phase 1: Local Commands (Priority 1)

Implement local commands first in simple-cli:

• compose (all 9 subcommands)
• db (all 3 subcommands)
• override

Phase 2: Daemon Commands (Priority 2)

Add daemon-based commands to full CLI:

• System management commands
• Package management commands
• Configuration commands

Phase 3: Architecture Alignment

• Keep same client/daemon split
• Use D-Bus for daemon communication
• Support container operations
• Preserve privilege separation

Phase 4: Package Management

• Replace RPM/DNF with APT/DPKG
• Maintain same operation semantics
• Support layered package management
• Implement transaction handling

Conclusion

The rpm-ostree execution model provides a sophisticated architecture with clear separation between daemon-based system operations and local development/debugging operations. For apt-ostree, maintaining this architecture while replacing the package management system will ensure compatibility and security.

The key insight is that most commands (15/21) use daemon communication for system operations, while compose, db, and override commands run locally for development and container workflows. This split enables both security (privileged operations in daemon) and flexibility (local execution for development).