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

rpm-ostree Command Analysis

Date: December 19, 2024
Source: Analysis of .notes/inspiration/rpm-ostree-main source code
Goal: Document how each command works, whether it runs via daemon or client, and its arguments

Architecture Overview

rpm-ostree uses a daemon/client architecture where commands are split into two categories:

Execution Model 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 (client-only)
• If not → uses daemon (daemon-based)

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;

Command Analysis

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 Commands

status - Get system version and deployment info

• Flags: 0 (no LOCAL_CMD)
• Execution: Daemon-based via D-Bus
• Arguments:
  • --verbose, -v: Print additional fields
  • --advisories, -a: Expand advisories listing
  • --json: Output JSON
  • --jsonpath, -J: Filter JSONPath expression
  • --booted, -b: Only print booted deployment
  • --pending-exit-77: Exit 77 if pending deployment available
• Functionality:
  • Connects to daemon via rpmostree_load_sysroot()
  • Gets deployments via rpmostree_sysroot_dup_deployments()
  • Queries systemd for auto-update state
  • Formats and displays deployment information

upgrade - Perform a system upgrade

• Flags: SUPPORTS_PKG_INSTALLS
• Execution: Daemon-based via D-Bus
• Arguments:
  • --reboot: Reboot after upgrade
  • --allow-downgrade: Allow downgrading packages
  • --preview: Show what would be downloaded
  • --check: Check for updates only
  • --cache-only: Only download, don't deploy
  • --download-only: Download only, don't deploy
  • --unchanged-exit-77: Exit 77 if no changes
  • --bypass-driver: Bypass automatic update driver
  • --install: Overlay additional package
  • --uninstall: Remove overlayed package
• Functionality: Initiates system upgrade transaction via daemon

rollback - Revert to previously booted tree

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments:
  • --reboot: Reboot after rollback
• Functionality: Reverts to previous deployment via daemon

deploy - Deploy a specific commit

• Flags: SUPPORTS_PKG_INSTALLS
• Execution: Daemon-based via D-Bus
• Arguments:
  • --revision: Deploy specific revision
  • --osname: OS name to deploy
  • --reboot: Reboot after deployment
  • --skip-purge: Skip purging old deployments
  • --install: Overlay additional package
  • --uninstall: Remove overlayed package
• Functionality: Deploys specific OSTree commit via daemon

rebase - Switch to different tree

• Flags: SUPPORTS_PKG_INSTALLS
• Execution: Daemon-based via D-Bus
• Arguments:
  • --branch: Branch to rebase to
  • --remote: Remote to use
  • --reboot: Reboot after rebase
  • --install: Overlay additional package
  • --uninstall: Remove overlayed package
• Functionality: Switches to different OSTree tree via daemon

reset - Remove all mutations

• Flags: SUPPORTS_PKG_INSTALLS
• Execution: Daemon-based via D-Bus
• Arguments:
  • --reboot: Reboot after reset
  • --install: Overlay additional package
  • --uninstall: Remove overlayed package
• Functionality: Removes all package overlays via daemon

apply-live - Apply pending deployment changes to booted deployment

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments:
  • --target: Target to apply to
  • --reset: Reset live changes
  • --allow-replacement: Allow replacement of files
• Functionality: Applies live changes to booted deployment via daemon

Package Management Commands

install - Overlay additional packages

• Flags: CONTAINER_CAPABLE
• Execution: Daemon-based via D-Bus
• Arguments:
  • --dry-run: Show what would be done
  • --yes, -y: Answer yes to prompts
• Functionality: Installs packages as overlays via daemon

uninstall - Remove overlayed additional packages

• Flags: CONTAINER_CAPABLE
• Execution: Daemon-based via D-Bus
• Arguments:
  • --dry-run: Show what would be done
  • --yes, -y: Answer yes to prompts
• Functionality: Removes package overlays via daemon

search - Search for packages

• Flags: CONTAINER_CAPABLE
• Execution: Daemon-based via D-Bus
• Arguments:
  • --advisories: Include security advisories
• Functionality: Searches for packages via daemon

System Configuration Commands

initramfs - Enable or disable local initramfs regeneration

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments:
  • --enable: Enable initramfs regeneration
  • --disable: Disable initramfs regeneration
• Functionality: Manages initramfs regeneration via daemon

initramfs-etc - Add files to the initramfs

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments:
  • --track: Track file for initramfs
  • --untrack: Untrack file from initramfs
• Functionality: Manages initramfs files via daemon

kargs - Query or modify kernel arguments

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments:
  • --append: Append kernel argument
  • --delete: Delete kernel argument
  • --replace: Replace kernel argument
  • --list: List current kernel arguments
• Functionality: Manages kernel arguments via daemon

cleanup - Clear cached/pending data

• Flags: CONTAINER_CAPABLE
• Execution: Daemon-based via D-Bus
• Arguments:
  • --base: Clean base layer
  • --pending: Clean pending deployments
• Functionality: Cleans up cached data via daemon

reload - Reload configuration

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments: None
• Functionality: Reloads daemon configuration

refresh-md - Generate rpm repo metadata

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments: None
• Functionality: Refreshes repository metadata via daemon

cancel - Cancel an active transaction

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments: None
• Functionality: Cancels active daemon transaction

finalize-deployment - Finalize deployment

• Flags: 0
• Execution: Daemon-based via D-Bus
• Arguments: None
• Functionality: Finalizes staged deployment

2. Local Commands (6/21 primary commands)

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

Compose System Commands

compose - Commands to compose a tree

• Flags: LOCAL_CMD | REQUIRES_ROOT
• Execution: Local (no daemon communication)
• Subcommands:
  • tree: Process treefile and commit to OSTree repository
    • Flags: LOCAL_CMD
    • Arguments: treefile, --repo, --force-nocache, --cachedir, --dry-run, --print-only
  • install: Install packages into target path
    • Flags: LOCAL_CMD | REQUIRES_ROOT
    • Arguments: treefile, destdir, --repo, --force-nocache, --cachedir, --dry-run
  • postprocess: Perform final postprocessing
    • Flags: LOCAL_CMD | REQUIRES_ROOT
    • Arguments: rootfs, treefile
  • commit: Commit target path to OSTree repository
    • Flags: LOCAL_CMD | REQUIRES_ROOT
    • Arguments: treefile, rootfs, --repo, --layer-repo, --write-commitid-to, --write-composejson-to
  • extensions: Download packages with depsolve guarantee
    • Flags: LOCAL_CMD
    • Arguments: treefile, extyaml, --repo, --layer-repo, --output-dir
  • container-encapsulate: Generate container image from OSTree commit
    • Flags: LOCAL_CMD
    • Arguments: ostree_ref, imgref, --repo, --label, --image-config
  • image: Generate container image from treefile
    • Flags: LOCAL_CMD
    • Arguments: manifest, output, --cachedir, --source-root, --authfile
  • rootfs: Generate root filesystem tree from treefile
    • Flags: LOCAL_CMD
    • Arguments: manifest, dest, --cachedir, --source-root
  • build-chunked-oci: Generate chunked OCI archive from rootfs
    • Flags: LOCAL_CMD
    • Arguments: output, --rootfs, --from, --bootc

Database Operations Commands

db - Commands to query the RPM database

• Flags: LOCAL_CMD
• Execution: Local (no daemon communication)
• Subcommands:
  • diff: Show package changes between commits
    • Flags: LOCAL_CMD
    • Arguments: commit1, commit2, --repo
  • list: List packages within commits
    • Flags: LOCAL_CMD
    • Arguments: commit, --repo
  • version: Show rpmdb version
    • Flags: LOCAL_CMD
    • Arguments: commit, --repo

Package Override Commands

override - Manage base package overrides

• Flags: LOCAL_CMD
• Execution: Local (no daemon communication)
• Arguments:
  • --reset: Reset overrides
  • --remove: Remove override
  • --replace: Replace override
• Functionality: Manages package overrides directly

Experimental/Internal Commands

ex - Experimental commands

• Flags: LOCAL_CMD | HIDDEN
• Execution: Local (no daemon communication)
• Functionality: Experimental features

testutils - Testing utilities

• Flags: LOCAL_CMD | HIDDEN
• Execution: Local (no daemon communication)
• Functionality: Testing utilities

shlib-backend - Shared library backend

• Flags: LOCAL_CMD | HIDDEN
• Execution: Local (no daemon communication)
• Functionality: Shared library backend operations

start-daemon - Start daemon

• Flags: LOCAL_CMD | REQUIRES_ROOT | HIDDEN
• Execution: Local (no daemon communication)
• Functionality: Starts the rpm-ostree daemon

3. Special Commands

usroverlay - Apply transient overlayfs to /usr

• Flags: REQUIRES_ROOT
• Execution: Local (Rust implementation)
• Arguments: None
• Functionality: Applies transient overlayfs to /usr

unlock - Alias for usroverlay

• Flags: REQUIRES_ROOT | HIDDEN
• Execution: Local (Rust implementation)
• Functionality: Alias for usroverlay

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

References

• Source code: .notes/inspiration/rpm-ostree-main/src/app/
• Command definitions: libmain.cxx
• Command flags: rpmostree-builtin-types.h
• Daemon communication: rpmostree-clientlib.cxx