particle-os-tools/docs/apt-layer/rpm-ostree/compose/extensions.md

rpm-ostree Extensions

Overview

rpm-ostree extensions provide a way to add optional system components without modifying the base image. Extensions are layered on top of the immutable base and can be enabled, disabled, or updated independently.

Extension Concepts

What are Extensions?

Extensions are optional system components that:

• Extend functionality: Add new capabilities to the base system
• Maintain immutability: Don't modify the base image
• Enable flexibility: Can be enabled/disabled as needed
• Support updates: Can be updated independently of the base

Extension Types

1. System Extensions: Core system functionality
2. Development Extensions: Development tools and libraries
3. Application Extensions: End-user applications
4. Hardware Extensions: Hardware-specific drivers and tools

Extension Architecture

Layering Model

System Layers
├── Base Image (immutable)
├── Extension Layer 1
├── Extension Layer 2
└── User Packages (layered)

Extension Structure

/usr/lib/extensions/
├── extension1/
│   ├── lib/
│   ├── bin/
│   └── metadata.json
├── extension2/
│   ├── lib/
│   ├── bin/
│   └── metadata.json
└── extension3/
    ├── lib/
    ├── bin/
    └── metadata.json

Extension Management

Installing Extensions

# Install system extension
rpm-ostree install --apply-live systemd-oomd

# Install development extension
rpm-ostree install --apply-live gcc make

# Install application extension
rpm-ostree install --apply-live vim emacs

Enabling Extensions

# Enable extension
rpm-ostree extension enable my-extension

# Enable multiple extensions
rpm-ostree extension enable extension1 extension2

# Enable with specific version
rpm-ostree extension enable my-extension:1.2.3

Disabling Extensions

# Disable extension
rpm-ostree extension disable my-extension

# Disable multiple extensions
rpm-ostree extension disable extension1 extension2

Listing Extensions

# List installed extensions
rpm-ostree extension list

# List available extensions
rpm-ostree extension list --available

# List with details
rpm-ostree extension list --verbose

Extension Configuration

Extension Metadata

{
  "name": "my-extension",
  "version": "1.2.3",
  "description": "My custom extension",
  "author": "Extension Author",
  "dependencies": ["base-extension"],
  "conflicts": ["conflicting-extension"],
  "provides": ["virtual-package"],
  "files": [
    "/usr/bin/my-tool",
    "/usr/lib/my-lib.so",
    "/etc/my-config.conf"
  ],
  "services": [
    "my-extension.service"
  ],
  "environment": {
    "PATH": "/usr/lib/extensions/my-extension/bin"
  }
}

Extension Dependencies

# Extension dependencies
dependencies:
  - base-extension
  - common-libs
  - system-tools

# Optional dependencies
optional-dependencies:
  - optional-tool
  - debug-tools

# Conflicts
conflicts:
  - conflicting-extension
  - old-version

Extension Services

# /usr/lib/extensions/my-extension/my-extension.service
[Unit]
Description=My Extension Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/lib/extensions/my-extension/bin/my-service
Restart=on-failure

[Install]
WantedBy=multi-user.target

Extension Development

Creating Extensions

Basic Extension Structure

my-extension/
├── metadata.json
├── bin/
│   └── my-tool
├── lib/
│   └── my-lib.so
├── etc/
│   └── my-config.conf
├── services/
│   └── my-extension.service
└── README.md

Extension Build Process

#!/bin/bash
# build-extension.sh

EXTENSION_NAME="my-extension"
EXTENSION_VERSION="1.2.3"
BUILD_DIR="/tmp/extension-build"

# Create build directory
mkdir -p "$BUILD_DIR/$EXTENSION_NAME"

# Copy files
cp -r bin lib etc services "$BUILD_DIR/$EXTENSION_NAME/"

# Create metadata
cat > "$BUILD_DIR/$EXTENSION_NAME/metadata.json" << EOF
{
  "name": "$EXTENSION_NAME",
  "version": "$EXTENSION_VERSION",
  "description": "My custom extension",
  "files": [
    "/bin/my-tool",
    "/lib/my-lib.so",
    "/etc/my-config.conf"
  ]
}
EOF

# Package extension
tar -czf "$EXTENSION_NAME-$EXTENSION_VERSION.tar.gz" -C "$BUILD_DIR" "$EXTENSION_NAME"

Extension Packaging

RPM Package

# my-extension.spec
Name: my-extension
Version: 1.2.3
Release: 1%{?dist}
Summary: My custom extension

Group: System Environment/Base
License: MIT
URL: https://example.com/my-extension

Source0: %{name}-%{version}.tar.gz

BuildArch: noarch

%description
My custom extension for rpm-ostree systems.

%files
%{_libdir}/extensions/%{name}/
%{_bindir}/my-tool
%{_libdir}/my-lib.so
%{_sysconfdir}/my-config.conf

%post
# Enable extension
rpm-ostree extension enable %{name}

%preun
# Disable extension
rpm-ostree extension disable %{name}

OCI Container

# Dockerfile for extension
FROM scratch

COPY my-extension/ /usr/lib/extensions/my-extension/

LABEL org.rpm-ostree.extension=true
LABEL org.rpm-ostree.extension.name=my-extension
LABEL org.rpm-ostree.extension.version=1.2.3

Extension Integration

Filesystem Integration

Extensions are integrated into the filesystem using overlay mounts:

# Mount extension
mount -t overlay overlay \
  -o lowerdir=/usr/lib/extensions/my-extension,upperdir=/run/extensions/my-extension,workdir=/run/extensions/work \
  /usr/lib/extensions/my-extension

Library Integration

Extensions can provide libraries that are automatically loaded:

# Add extension library path
export LD_LIBRARY_PATH="/usr/lib/extensions/my-extension/lib:$LD_LIBRARY_PATH"

# Or use ldconfig
echo "/usr/lib/extensions/my-extension/lib" > /etc/ld.so.conf.d/my-extension.conf
ldconfig

Service Integration

Extensions can provide systemd services:

# Enable extension services
systemctl enable my-extension.service

# Start extension services
systemctl start my-extension.service

Extension Lifecycle

Installation Lifecycle

1. Download: Extension package is downloaded
2. Extract: Extension files are extracted
3. Validate: Extension metadata is validated
4. Install: Extension is installed to /usr/lib/extensions/
5. Enable: Extension is enabled and integrated

Update Lifecycle

1. Check: Check for extension updates
2. Download: Download updated extension
3. Backup: Backup current extension
4. Update: Install updated extension
5. Restart: Restart extension services

Removal Lifecycle

1. Disable: Extension is disabled
2. Stop: Extension services are stopped
3. Remove: Extension files are removed
4. Cleanup: Clean up any remaining files

Extension Security

Isolation

Extensions are isolated from the base system:

# Extension isolation
chroot /usr/lib/extensions/my-extension /bin/bash

# Namespace isolation
unshare --mount --uts --ipc --net --pid -- chroot /usr/lib/extensions/my-extension /bin/bash

Permissions

Extensions have limited permissions:

# Extension permissions
chmod 755 /usr/lib/extensions/my-extension
chown root:root /usr/lib/extensions/my-extension

Validation

Extensions are validated before installation:

# Validate extension
rpm-ostree extension validate my-extension

# Check extension integrity
rpm-ostree extension verify my-extension

Extension Examples

Development Extension

{
  "name": "dev-tools",
  "version": "1.0.0",
  "description": "Development tools extension",
  "dependencies": ["base-tools"],
  "files": [
    "/usr/bin/gcc",
    "/usr/bin/make",
    "/usr/bin/git",
    "/usr/lib/gcc/",
    "/usr/include/"
  ],
  "environment": {
    "PATH": "/usr/bin:/usr/lib/extensions/dev-tools/bin",
    "CC": "gcc",
    "MAKE": "make"
  }
}

Monitoring Extension

{
  "name": "monitoring",
  "version": "1.0.0",
  "description": "System monitoring extension",
  "files": [
    "/usr/bin/prometheus",
    "/usr/bin/grafana",
    "/etc/prometheus/",
    "/etc/grafana/"
  ],
  "services": [
    "prometheus.service",
    "grafana.service"
  ],
  "environment": {
    "PROMETHEUS_CONFIG": "/etc/prometheus/prometheus.yml",
    "GRAFANA_CONFIG": "/etc/grafana/grafana.ini"
  }
}

Hardware Extension

{
  "name": "nvidia-drivers",
  "version": "470.0.0",
  "description": "NVIDIA GPU drivers",
  "hardware": ["nvidia"],
  "files": [
    "/usr/lib/nvidia/",
    "/usr/bin/nvidia-smi",
    "/etc/modprobe.d/nvidia.conf"
  ],
  "kernel-modules": [
    "nvidia",
    "nvidia-drm",
    "nvidia-uvm"
  ],
  "services": [
    "nvidia-persistenced.service"
  ]
}

Extension Management Tools

Command Line Tools

# Extension management commands
rpm-ostree extension install my-extension
rpm-ostree extension update my-extension
rpm-ostree extension remove my-extension
rpm-ostree extension list
rpm-ostree extension info my-extension

Configuration Management

# Extension configuration
rpm-ostree extension config my-extension set key=value
rpm-ostree extension config my-extension get key
rpm-ostree extension config my-extension list

Monitoring and Logging

# Extension monitoring
rpm-ostree extension status my-extension
rpm-ostree extension logs my-extension
rpm-ostree extension health my-extension

Best Practices

Extension Design

1. Minimal dependencies: Keep dependencies minimal
2. Clear interfaces: Define clear extension interfaces
3. Version compatibility: Ensure version compatibility
4. Documentation: Provide comprehensive documentation

Extension Management

1. Regular updates: Keep extensions updated
2. Testing: Test extensions thoroughly
3. Monitoring: Monitor extension health
4. Backup: Backup extension configurations

Security

1. Validation: Validate extension integrity
2. Isolation: Maintain extension isolation
3. Permissions: Use minimal required permissions
4. Audit: Audit extension activities

---

Extensions provide a flexible way to extend rpm-ostree systems while maintaining the immutability and atomicity of the base image.