Skip to content

flmadm

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

flmadm

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 

README.md

flmadm - Flame Administration Tool

flmadm is the administration CLI for Flame, designed for installing, configuring, and managing Flame clusters on bare-metal servers or VMs.

Overview

Flame provides two separate CLI tools:

  • flmctl: User-facing CLI for submitting jobs and managing sessions
  • flmadm: Administrator CLI for installation and cluster management

Features

  • Automated Installation: One-command installation of all Flame components
  • Source Building: Builds Flame binaries from source (Rust)
  • Python SDK Installation: Automatically installs the Flame Python SDK
  • Systemd Integration: Generates and manages systemd service files
  • Configuration Generation: Creates default configuration files
  • Clean Uninstallation: Safely removes Flame with backup support
  • Flexible Installation: Supports both system-wide (root) and user-local installations
  • Installation Profiles: Install specific components (control-plane, worker, client)

Installation

To install flmadm itself, build it from source:

cd /path/to/flame
cargo build --release -p flmadm
sudo cp target/release/flmadm /usr/local/bin/

Or use an existing installation:

sudo flmadm install

Usage

Install Flame

Basic installation (all components):

sudo flmadm install --all

Install from local source:

sudo flmadm install --all --src-dir /path/to/flame

Custom installation directory:

sudo flmadm install --all --prefix /opt/flame

Install and start services:

sudo flmadm install --all --enable

User-local installation (no systemd):

flmadm install --no-systemd --prefix ~/flame

Clean install (backup and reinstall):

sudo flmadm install --clean --enable

Verbose build output:

sudo flmadm install --verbose

Install specific profiles:

# Install all components explicitly (same as default)
sudo flmadm install --all

# Control plane only (session manager, flmctl, flmadm)
sudo flmadm install --control-plane

# Worker only (executor manager, services, SDK)
sudo flmadm install --worker

# Client only (flmping, flmexec, SDK)
sudo flmadm install --client

# Combined installation (control plane + worker on same node)
sudo flmadm install --control-plane --worker --enable

# Force overwrite existing components
sudo flmadm install --worker --force

# Client installation (no systemd needed)
flmadm install --client --prefix ~/flame

# ERROR: Cannot use --enable with client-only
# flmadm install --client --enable  # This will fail with an error

# ERROR: Cannot use --all with specific profiles
# sudo flmadm install --all --control-plane  # This will fail with an error

Uninstall Flame

Basic uninstall (with backup):

sudo flmadm uninstall

Uninstall and preserve data:

sudo flmadm uninstall --preserve-data --preserve-config

Uninstall from custom location:

sudo flmadm uninstall --prefix /opt/flame

Complete removal (no backup):

sudo flmadm uninstall --no-backup --force

Custom backup location:

sudo flmadm uninstall --backup-dir /backups/flame-backup-2026-01-28

Install Options

  • --src-dir <PATH>: Source code directory for building Flame (default: clone from GitHub)
  • --prefix <PATH>: Target installation directory (default: /usr/local/flame)
  • --all: Explicitly install all components (control plane + worker + client)
  • --control-plane: Install control plane components only (flame-session-manager, flmctl, flmadm)
  • --worker: Install worker components only (flame-executor-manager, flmping-service, flmexec-service, flamepy)
  • --client: Install client components only (flmping, flmexec, flamepy)
  • --no-systemd: Skip systemd service generation (for user-local installs)
  • --enable: Enable and start systemd services after installation
  • --skip-build: Skip building from source (use pre-built binaries)
  • --clean: Remove existing installation before installing (creates backup)
  • --force: Force overwrite existing components without prompting
  • --verbose: Show detailed build output (useful for debugging build issues)

Note:

  • You must specify at least one profile flag (--all, --control-plane, --worker, or --client)
  • The --all flag cannot be combined with --control-plane, --worker, or --client
  • Profile flags can be combined (e.g., --control-plane --worker for a combined node)

Installation Profiles

Flame supports three installation profiles to allow flexible deployment architectures:

Control Plane Profile (--control-plane)

Installs components required for cluster management:

  • flame-session-manager: Main control plane service
  • flmctl: CLI for job submission and management
  • flmadm: Administration CLI

Use case: Deploy on dedicated control plane nodes that manage the cluster but don't execute workloads.

Worker Profile (--worker)

Installs components required for executing workloads:

  • flame-executor-manager: Worker node service
  • flmping-service: Health check service
  • flmexec-service: Execution service
  • flamepy: Python SDK

Use case: Deploy on worker nodes that execute user workloads.

Client Profile (--client)

Installs client tools for submitting jobs:

  • flmctl: CLI for job submission and session management
  • flmping: CLI for health checks
  • flmexec: CLI for job execution
  • flamepy: Python SDK

Use case: Deploy on client machines or jump hosts for users to submit jobs without running services.

Note: The client profile doesn't install any systemd services. The --enable flag is not applicable when only --client is specified. The --no-systemd flag is automatically implied for client-only installations.

Combined Deployments

Profiles can be combined in a single installation:

# Single-node deployment (all-in-one)
sudo flmadm install --control-plane --worker --enable

# Control plane + client tools
sudo flmadm install --control-plane --client

# Worker + client tools
sudo flmadm install --worker --client

Component Overwrite Behavior

When installing over an existing installation:

  • Without --force: Prompts for confirmation before overwriting each existing component
  • With --force: Automatically overwrites all components without prompting
  • With --clean: Backs up and removes the entire installation before installing

Uninstall Options

  • --prefix <PATH>: Installation directory to uninstall (default: /usr/local/flame)
  • --preserve-data: Preserve data directory (useful for reinstallation)
  • --preserve-config: Preserve configuration files
  • --preserve-logs: Preserve log files
  • --backup-dir <PATH>: Custom backup directory
  • --no-backup: Do not create backup (PERMANENTLY DELETE - use with caution!)
  • --force: Skip confirmation prompts

Directory Structure

After installation, Flame uses the following directory structure:

${PREFIX}/
├── bin/                    # Flame binaries
│   ├── flame-session-manager
│   ├── flame-executor-manager
│   ├── flmctl
│   └── flmadm
├── sdk/python/             # Python SDK
├── work/                   # Working directory
│   ├── sessions/
│   └── executors/
├── logs/                   # Log files
│   ├── fsm.log
│   └── fem.log
├── conf/                   # Configuration
│   └── flame-cluster.yaml
└── data/                   # Data directory (cache, database)
    ├── cache/
    └── sessions.db

Service Management

After installation with systemd, manage services using standard systemctl commands:

# Start services
sudo systemctl start flame-session-manager
sudo systemctl start flame-executor-manager

# Stop services
sudo systemctl stop flame-executor-manager
sudo systemctl stop flame-session-manager

# Enable on boot
sudo systemctl enable flame-session-manager flame-executor-manager

# Check status
sudo systemctl status flame-session-manager
sudo systemctl status flame-executor-manager

# View logs
sudo journalctl -u flame-session-manager -f
tail -f /usr/local/flame/logs/fsm.log

Prerequisites

  • Rust toolchain: Required for building from source (unless --skip-build)
    • Install: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • Git: Required for cloning from GitHub (unless --src-dir provided)
  • pip/pip3: Required for installing Python SDK
  • systemd: Required for service management (unless --no-systemd)
  • Root privileges: Required for system-wide installation with systemd

Examples

Development Workflow

# Developer working on Flame source
cd ~/projects/flame
flmadm install --src-dir . --prefix ~/flame --no-systemd

# Make changes, rebuild
cargo build --release

# Reinstall with updated binaries
flmadm install --src-dir . --prefix ~/flame --skip-build --no-systemd --clean

Production Deployment

# Single-node deployment (all components)
sudo flmadm install --enable

# Multi-node deployment: Control plane node
sudo flmadm install --control-plane --enable

# Multi-node deployment: Worker nodes
sudo flmadm install --worker --enable

# Client machine (no services)
flmadm install --client --prefix ~/flame --no-systemd

# Verify installation
sudo systemctl status flame-session-manager flame-executor-manager
/usr/local/flame/bin/flmctl --version

# Upgrade to new version
sudo systemctl stop flame-executor-manager flame-session-manager
sudo flmadm install --clean
sudo systemctl start flame-session-manager flame-executor-manager

Distributed Cluster Setup

# On control plane node (control01)
sudo flmadm install --control-plane --enable

# On worker nodes (worker01, worker02, ...)
sudo flmadm install --worker --enable

# On client/jump host (for users)
flmadm install --client --prefix ~/flame --no-systemd

# Update only worker nodes
sudo flmadm install --worker --force --skip-build

Testing and Cleanup

# Install for testing
sudo flmadm install --prefix /tmp/flame-test --no-systemd

# Test the installation
/tmp/flame-test/bin/flmctl --version

# Clean up
flmadm uninstall --prefix /tmp/flame-test --no-backup --force

Troubleshooting

Build Failures

If the build fails, use --verbose to see full cargo output:

sudo flmadm install --verbose

Build logs are also saved to /tmp/flame-install-build.log for offline debugging.

Permission Errors

For system-wide installation, run with sudo:

sudo flmadm install

For user-local installation, use --no-systemd:

flmadm install --no-systemd --prefix ~/flame

Service Start Failures

Check service status and logs:

sudo systemctl status flame-session-manager
sudo journalctl -u flame-session-manager -n 50
tail -50 /usr/local/flame/logs/fsm.log

Uninstall Safety

flmadm includes safety checks to prevent accidental system damage:

  • Cannot uninstall from system paths like /, /usr, /etc
  • Installation path must contain "flame" in its name
  • Requires confirmation unless --force is used
  • Creates backup by default before removal

Exit Codes

  • 0: Success
  • 1: Invalid arguments or configuration
  • 2: Build failure
  • 3: Installation failure (permissions, disk space, etc.)
  • 4: Systemd configuration failure
  • 5: Service start failure

See Also

License

Same as Flame project license.