apt-ostree/.notes/cli_analysis/client_daemon_execution_summary.md

rpm-ostree Client/Daemon Execution Model Summary

Overview

This document summarizes the client/daemon execution model in rpm-ostree based on deep source code analysis. Understanding this model is crucial for implementing apt-ostree with the same architecture.

Key Decision Logic

The execution model is determined by the LOCAL_CMD flag in the command definition:

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

Simple rule: If a command has LOCAL_CMD flag → runs locally. If not → uses daemon.

Command Execution Categories

1. Daemon-Based Commands (15/21 primary commands)

These commands DO NOT have the LOCAL_CMD flag and communicate with the daemon via D-Bus:

System Management

• status - Get system version and deployment info
• upgrade - Perform system upgrade
• rollback - Revert to previously booted tree
• reset - Remove all mutations
• rebase - Switch to different tree
• deploy - Deploy specific commit
• 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

2. Local Commands (6/21 primary commands)

These commands HAVE the LOCAL_CMD flag and run directly without daemon communication:

Compose System

• compose - Commands to compose a tree (9 subcommands)
  • All compose subcommands run locally
  • 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 Architecture

D-Bus Interface

#define BUS_NAME "org.projectatomic.rpmostree1"

Connection Pattern

// 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;

Key Client Library Functions

• rpmostree_load_sysroot() - Connect to daemon
• rpmostree_load_os_proxy() - Get OS proxy
• rpmostree_transaction_client_run() - Execute transactions
• rpmostree_update_deployment() - Update deployments

Option Parsing Differences

Daemon-Based Commands

Get these additional options:

• --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

Only get:

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

Privilege Requirements

Root-Required Commands

Commands with REQUIRES_ROOT flag:

• compose - Commands to compose a tree
• usroverlay - Apply transient overlayfs to /usr
• unlock - Alias for usroverlay
• start-daemon - Start daemon

Container-Capable Commands

Commands with CONTAINER_CAPABLE flag:

• cleanup - Clear cached/pending data
• install - Overlay additional packages
• uninstall - Remove overlayed packages
• search - Search for packages

Implementation Implications for apt-ostree

1. Architecture Alignment

• Maintain same split: 15 daemon-based, 6 local commands
• Daemon communication: Use D-Bus for system operations
• Local execution: Direct execution for compose/db/override
• Privilege separation: Daemon handles privileged operations

2. Command Implementation Strategy

Daemon-Based Commands (15 commands)

• Implement D-Bus client communication
• Use daemon for privileged operations
• Support package operations via daemon
• Handle system state changes

Local Commands (6 commands)

• Direct execution without daemon
• Compose commands: Direct OSTree operations
• DB commands: Direct package database queries
• Override commands: Direct package overrides

3. Package Management Integration

• Daemon-based: install, uninstall, search via daemon
• Local: compose install, db operations directly
• Replace RPM/DNF: Use APT/DPKG for all operations
• Maintain semantics: Same behavior and output

4. Compose System Priority

• All 9 subcommands: Essential for container workflows
• Local execution: No daemon communication required
• OCI integration: Container image generation
• Treefile processing: Declarative system management

Key Insights

1. Most Commands Use Daemon (15/21)

The majority of commands use daemon communication for:

• Privilege separation
• System state management
• Package operations
• Transaction handling

2. Compose System is Local

All compose commands run locally, enabling:

• Container workflows
• CI/CD integration
• Offline operations
• Direct OSTree manipulation

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. Architecture Benefits

• Security: Privileged operations isolated in daemon
• Flexibility: Local commands for development/debugging
• Performance: Direct execution for compose operations
• Compatibility: Same CLI interface as rpm-ostree

Implementation Recommendations

1. Start with Local Commands

Implement local commands first in simple-cli:

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

2. Extend Daemon Commands

Add daemon-based commands to full CLI:

• System management commands
• Package management commands
• Configuration commands

3. Maintain Architecture

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

4. Package Management

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

Conclusion

The rpm-ostree client/daemon architecture provides a sophisticated model for system management with proper privilege separation and flexible execution patterns. 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).