Technical Details - buggerman/re-arch GitHub Wiki

██████╗ ███████╗      █████╗ ██████╗  ██████╗██╗  ██╗
██╔══██╗██╔════╝     ██╔══██╗██╔══██╗██╔════╝██║  ██║
██████╔╝█████╗  ████╗███████║██████╔╝██║     ███████║
██╔══██╗██╔══╝  ╚═══╝██╔══██║██╔══██╗██║     ██╔══██║
██║  ██║███████╗     ██║  ██║██║  ██║╚██████╗██║  ██║
╚═╝  ╚═╝╚══════╝     ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝

RE-ARCH Technical Details

Advanced technical information about RE-ARCH system architecture, configurations, and optimizations.

🏗️ System Architecture

Installation Method

Two-Phase Architecture:

  1. Phase 1: archinstall handles 80% of the work (base system, packages, desktop environment)
  2. Phase 2: re-arch-lite.sh handles 20% of the work (configuration, services, optimizations)

Benefits:

  • Leverages proven archinstall for package management
  • Reduces custom code maintenance burden
  • Provides clear separation of concerns
  • Enables reliable fallback mechanisms

Boot Process

Boot Sequence:

  1. UEFI/BIOS → GRUB → Linux Zen Kernel → systemd → Display Manager → Desktop Environment

Key Components:

  • Bootloader: GRUB with Btrfs snapshot support
  • Kernel: linux-zen optimized for desktop performance
  • Init System: systemd with custom service configurations
  • Display Manager: Desktop environment specific (SDDM/GDM/LightDM)

💾 Filesystem Architecture

Btrfs Subvolume Layout

Subvolume Structure:

/dev/sdXY (Btrfs root)
├── @ → / (root filesystem)
├── @home → /home (user data)
├── @log → /var/log (system logs)
└── @pkg → /var/cache/pacman/pkg (package cache)

Benefits:

  • Isolated snapshots: Each subvolume can be snapshotted independently
  • Efficient storage: Copy-on-write reduces disk usage
  • Flexible management: Subvolumes can be managed separately
  • Performance: Optimized for SSD and modern storage

Compression and Optimization

Compression Settings:

  • Algorithm: zstd (Zstandard)
  • Level: Default (balanced compression/speed)
  • Mount options: compress=zstd,noatime,space_cache=v2

Performance Benefits:

  • Reduced I/O: Compressed data reduces disk reads/writes
  • SSD friendly: noatime reduces write amplification
  • Modern caching: space_cache=v2 improves performance

📸 Snapshot Management

Snapper Configuration

Snapshot Types:

  • Timeline snapshots: Automatic periodic snapshots
  • Pre/Post snapshots: Before/after package operations
  • Boot snapshots: Bootable recovery points

Configuration Details:

# Snapper config location
/etc/snapper/configs/root

# Key settings
SUBVOLUME="/"
TIMELINE_CREATE="yes"
TIMELINE_CLEANUP="yes"
NUMBER_LIMIT="10"
NUMBER_LIMIT_IMPORTANT="5"

GRUB Integration

grub-btrfs Features:

  • Automatic detection: Scans for available snapshots
  • Boot menu integration: Snapshots appear in GRUB menu
  • Read-only boot: Snapshots are mounted read-only for safety
  • Rollback support: Easy system recovery

Configuration:

# GRUB Btrfs settings
GRUB_BTRFS_LIMIT="10"
GRUB_BTRFS_SHOW_SNAPSHOTS_FOUND="true"

⚡ Performance Optimizations

Kernel Selection

linux-zen Features:

  • Desktop optimizations: Tuned for interactive performance
  • Scheduler improvements: Better process scheduling
  • Memory management: Optimized for desktop workloads
  • I/O improvements: Better file system performance

Process Optimization

ananicy-cpp:

  • Automatic nice levels: Adjusts process priorities
  • Desktop responsiveness: Prioritizes interactive applications
  • Game optimization: Optimizes for gaming workloads
  • System rules: Predefined rules for common applications

Configuration:

# Service location
/etc/systemd/system/ananicy-cpp.service

# Rules location
/etc/ananicy.d/

Memory Management

zram-generator:

  • Compressed swap: RAM-based compressed swap
  • Improved responsiveness: Reduces disk I/O for swapping
  • Configurable size: Typically 50% of available RAM
  • Automatic setup: Configured during installation

Configuration:

# Config location
/etc/systemd/zram-generator.conf

# Example settings
[zram0]
zram-size = ram / 2
compression-algorithm = zstd

🔊 Audio System

PipeWire Architecture

Components:

  • pipewire: Core audio server
  • pipewire-pulse: PulseAudio compatibility
  • pipewire-alsa: ALSA compatibility
  • pipewire-jack: JACK compatibility
  • wireplumber: Session manager

Benefits:

  • Low latency: Designed for professional audio
  • Unified handling: Audio, video, and MIDI in one system
  • Compatibility: Works with existing applications
  • Modern design: Built for containerized applications

Configuration

User session:

# PipeWire user services
systemctl --user enable pipewire.service
systemctl --user enable pipewire-pulse.service
systemctl --user enable wireplumber.service

🔥 Security Configuration

Firewall Setup

firewalld Configuration:

  • Default zone: Public (restrictive)
  • Enabled services: SSH (if needed)
  • Logging: Denied packets logged
  • Rich rules: Custom rule support

Key Files:

# Main configuration
/etc/firewalld/firewalld.conf

# Zone configurations
/etc/firewalld/zones/

# Service definitions
/etc/firewalld/services/

System Hardening

Default Hardening:

  • User isolation: Non-root user with sudo access
  • Service minimization: Only essential services enabled
  • Package verification: GPG signature verification
  • Secure defaults: Conservative security settings

🔧 Service Management

Enabled Services

System Services:

# Core services
systemd-networkd.service    # Network management
systemd-resolved.service    # DNS resolution
systemd-timesyncd.service   # Time synchronization

# Re-Arch specific
firewalld.service           # Firewall
snapper-timeline.timer      # Snapshot automation
snapper-cleanup.timer       # Snapshot cleanup
grub-btrfsd.service        # GRUB Btrfs integration
ananicy-cpp.service        # Process optimization

Desktop Services:

# KDE
sddm.service               # Display manager
bluetooth.service          # Bluetooth support

# GNOME
gdm.service               # Display manager
bluetooth.service         # Bluetooth support

# XFCE/Hyprland
lightdm.service           # Display manager
bluetooth.service         # Bluetooth support

Service Detection Logic

Dynamic Service Enablement:

# Detection logic (simplified)
detect_desktop_environment() {
    if pacman -Qq plasma-desktop 2>/dev/null; then
        echo "kde"
    elif pacman -Qq gnome-shell 2>/dev/null; then
        echo "gnome"
    elif pacman -Qq xfce4 2>/dev/null; then
        echo "xfce"
    elif pacman -Qq hyprland 2>/dev/null; then
        echo "hyprland"
    else
        echo "unknown"
    fi
}

get_display_manager() {
    local de="$1"
    case "$de" in
        "kde")     echo "sddm.service" ;;
        "gnome")   echo "gdm.service" ;;
        "xfce"|"hyprland") echo "lightdm.service" ;;
        *)         
            echo "Warning: Unknown desktop environment '$de', defaulting to sddm" >&2
            echo "sddm.service" 
            ;;
    esac
}

📦 Package Configuration

pacman Optimization

Configuration (/etc/pacman.conf):

# Performance
ParallelDownloads = 5
Color
VerbosePkgLists

# Repositories
[core]
[extra]
[multilib]  # 32-bit support

Mirror Optimization

reflector Configuration:

# Automatic mirror selection
reflector --country "United States,Canada,Germany,France,United Kingdom" \
          --protocol https \
          --latest 10 \
          --sort rate \
          --save /etc/pacman.d/mirrorlist

Flatpak Configuration

Repository Setup:

# System-wide Flathub
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

# User-specific (fallback)
flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo

🔍 Monitoring and Diagnostics

System Monitoring

Key Commands:

# System information
systemctl status
journalctl -b
systemd-analyze blame
systemd-analyze plot > boot-analysis.svg

# Resource usage
htop
iotop
nethogs

Log Management

Important Log Locations:

# System logs
/var/log/journal/
/var/log/pacman.log
/var/log/Xorg.0.log

# Re-Arch logs
/var/log/re-arch-lite.log

Performance Analysis

Boot Performance:

# Boot time analysis
systemd-analyze
systemd-analyze blame
systemd-analyze critical-chain

# Service startup times
systemd-analyze plot > boot-plot.svg

🛠️ Customization Points

User Customizations

Safe Customization Areas:

  • Desktop environment settings
  • Application preferences
  • User-specific configurations
  • Additional Flatpak applications

Areas to Avoid:

  • System service modifications
  • Core package replacements
  • Filesystem structure changes
  • Security service modifications

Advanced Customizations

For experienced users:

  • Custom kernel compilation
  • Additional system services
  • Advanced Btrfs layouts
  • Custom security policies

Backup Before Customization:

# Create snapshot before major changes
sudo snapper create --description "Before customization"

🔄 Update Mechanisms

System Updates

Update Process:

  1. Pre-snapshot: Automatic snapshot before updates
  2. Package update: pacman updates system packages
  3. Post-snapshot: Automatic snapshot after updates
  4. Verification: System integrity checks

Update Command:

# Full system update with snapshot
sudo pacman -Syu
# Snapshots are automatic via snap-pac

Configuration Updates

Re-Arch Updates:

# Update optimization script
curl -fsSL https://re-arch.xyz/re-arch-lite.sh | bash

# Update archinstall configs (for new installations)
# No direct update mechanism for existing systems

🔧 Advanced Troubleshooting

Debug Mode

Enable Debug Logging:

# Boot with debug kernel parameters
# Add to GRUB: systemd.log_level=debug

# Runtime debug
systemctl set-log-level debug

Recovery Procedures

System Recovery:

  1. Boot from snapshot: Use GRUB snapshot menu
  2. Chroot recovery: Boot from Arch ISO, mount system
  3. Service recovery: Disable problematic services
  4. Package recovery: Downgrade problematic packages

Emergency Commands:

# Disable problematic service
systemctl disable problematic.service

# Boot to rescue mode
systemctl isolate rescue.target

# Emergency shell
systemctl isolate emergency.target

For user-facing documentation, see Installation Guide and Post-Installation Setup.