SteamRoller

SteamRoller is an operator-oriented Ansible tool for assessing remote Red Hat Enterprise Linux 8.0-8.10 and RHEL 9 systems from a RHEL 9 or RHEL 10 control node. It provides multi-host prechecks, persistent evidence, repository safety controls, and a confirmed sequential multi-host reboot workflow.

Current version: 0.3.3

Highlights

• multi-host inventories with built-in create, add, delete, and list commands;
• SSH connectivity and root-execution validation;
• dedicated SSH key profiles with automatic private-key discovery;
• RHEL, kernel, uptime, DNF/RPM, disk, local-filesystem inode, fstab, network, and systemd checks;
• Red Hat CDN and Satellite auto-detection, including Simple Content Access;
• Satellite Organization, Lifecycle Environment, Content View, and repository evidence;
• custom .repo detection and explicit repository quarantine with local backup;
• PostgreSQL package, provenance, and available-version reporting;
• controlled sequential reboot of one or more selected inventory hosts with per-host PRE/POST validation;
• interactive DNF update of exactly one inventory host with native confirmation;
• readable fleet summaries plus per-host text and JSON reports;
• Bash completion for commands, inventories, hosts, options, and SSH profiles;
• optional host-scoped connectivity, precheck, and repository checks using a repeatable --host selector;
• inode thresholds applied only to local filesystems, with remote mounts listed as excluded evidence;
• complete dnf check dependency errors displayed in the terminal summary.

SteamRoller does not perform unattended fleet updates, change Satellite assignments, or coordinate clusters and HA applications.

Requirements

Control node:

• RHEL 9 or RHEL 10;
• Ansible Core;
• Python 3 and PyYAML;
• OpenSSH client and ping;
• Git for source-based installation.

RHEL 8.6 or later can be used as an experimental source-based control node. SteamRoller scripts are compatible with the system Python 3.6 shipped by RHEL 8, but the RHEL 8 control-node workflow still requires full validation.

RHEL 8.6+ control-node mini-HOWTO

Confirm the RHEL release and registration:

cat /etc/redhat-release
subscription-manager identity
subscription-manager status

For a host registered directly with Red Hat CDN, enable BaseOS and AppStream:

subscription-manager repos \
  --enable=rhel-8-for-x86_64-baseos-rpms \
  --enable=rhel-8-for-x86_64-appstream-rpms

On a Satellite-managed host, provide those repositories through its Content View instead of enabling CDN repositories manually. Verify the enabled content:

dnf repolist --enabled

Install the required RPM packages:

dnf install -y \
  ansible-core \
  python3 \
  python3-pyyaml \
  git \
  openssh-clients \
  iputils \
  bash-completion

Install rpm-build only when RPM development tools are needed:

dnf install -y rpm-build

Download and register the source command:

cd /root
git clone https://github.com/markhawks/SteamRoller.git
cd SteamRoller
./setup/manual/install-source-path.sh
source /root/.bashrc

Validate the installation:

python3 --version
ansible --version
python3 -c 'import yaml; print(yaml.__version__)'
steamroller version
steamroller inventory list

Expected SteamRoller version:

0.3.3

Managed hosts:

• RHEL 8.0 through RHEL 8.10, or RHEL 9.x;
• SSH access;
• Python available to Ansible;
• root access, currently used directly by the initial release.

For RHEL 8 managed hosts, BaseOS and AppStream must be available from Red Hat CDN or Satellite, and subscription-manager, DNF, RPM, systemd, findmnt, and the normal RHEL Python runtime must be present. Environment-specific required repository IDs should match the host major version; do not apply RHEL 9 repo IDs to RHEL 8 inventories.

Install the reboot-hint plug-in on RHEL 8 managed hosts when it is not already present:

dnf install -y yum-utils

SteamRoller also compares the running kernel with the newest installed kernel, so a kernel-driven reboot requirement remains visible even if the plug-in returns an unreliable result.

Quick start from source

git clone https://github.com/markhawks/SteamRoller.git
cd SteamRoller

./setup/manual/install-source-path.sh
source /root/.bashrc

steamroller version

The installer adds the current checkout to root's PATH, enables Bash completion, installs the strl short command, creates a timestamped .bashrc backup, and is safe to run again.

Both command names are equivalent:

steamroller version
strl version

strl inventory list
strl precheck ORION-LAB -q -sk foreman

Run a check on only one inventory host with --host:

strl connectivity ORION-LAB --host velora-db-a01.ops.example -q -sk foreman
strl precheck ORION-LAB --host velora-db-a01.ops.example -q -sk foreman

Repeat --host to check a selected subset. SteamRoller validates every name against the inventory and limits both execution and the final report to the selected hosts. Bash completion suggests inventory host names after --host.

For source installations, strl is a managed symbolic link:

/usr/local/bin/strl -> PROJECT_ROOT/bin/steamroller

The installer refuses to overwrite an existing strl command that it does not manage. Check for a collision before installation with:

command -v strl
type -a strl
dnf provides '*/bin/strl'

Running the installer with --remove removes both the managed Bash block and the managed strl link. RPM installations provide /usr/bin/steamroller and /usr/bin/strl.

Create an inventory:

steamroller inventory create -i ORION-LAB \
  -h velora-db-a01.ops.example \
  -h velora-db-a02.ops.example

Create an SSH key profile:

mkdir -p ssh-keys/foreman
cp /secure/path/id_rsa_foreman_proxy ssh-keys/foreman/
chmod 700 ssh-keys ssh-keys/foreman
chmod 600 ssh-keys/foreman/id_rsa_foreman_proxy

Run connectivity and precheck:

steamroller connectivity ORION-LAB -q -sk foreman
steamroller precheck ORION-LAB -q -sk foreman

If only one managed private key exists, -sk foreman can be omitted.

Safe mutating operations

Normal precheck is read-only. Repository quarantine is performed only when the operator explicitly requests it:

steamroller repo-off ORION-LAB -q -sk foreman

# Or quarantine first, then run precheck:
steamroller precheck ORION-LAB --repo-off -q -sk foreman

This backs up custom .repo files locally before moving them beneath /etc/yum.repos.d/SteamRoller-RepoOff/RUN_ID/ on the managed host.

Reboot accepts one or more exact inventory hosts and asks for one confirmation containing the complete ordered host list unless --confirm is supplied:

steamroller reboot ORION-LAB \
  --host velora-db-a01.ops.example \
  --host velora-db-a02.ops.example \
  -sk foreman

Hosts are rebooted sequentially (serial: 1). SteamRoller never interprets reboot as an entire-inventory operation; every target must be supplied with its own --host option.

An update also targets exactly one host. It runs the full precheck first, stops on any blocking failure, then displays the native DNF transaction and requires the operator to answer DNF's Is this ok [y/N] prompt:

steamroller update ORION-LAB \
  --host velora-db-a01.ops.example \
  -sk foreman

The update command requires an interactive terminal, has no quiet mode, saves the DNF transaction log, performs post-update validation, and never reboots the host automatically. Its final summary prints the complete SteamRoller reboot command for that host.

After reviewing a failed first pass, policy findings can be explicitly overridden with -F or --force:

steamroller update ORION-LAB \
  --host velora-db-a01.ops.example \
  -sk foreman \
  --force

SteamRoller displays every overridden finding and requires the operator to type FORCE UPDATE HOST. Missing mounts, insufficient disk space, DNF/RPM health or locking failures, unsupported systems, unavailable required repositories, and collection failures remain hard blockers. A mandatory fstab mount reported as read-only is overridable; a critical filesystem such as / or /boot being read-only remains blocking. Forced runs can never finish as PASS.

For legacy installations that modified the vendor PostgreSQL systemd unit, SteamRoller can preserve it during the update:

steamroller update ORION-LAB \
  --host velora-db-a01.ops.example \
  -sk foreman \
  --preserve-postgresql-unit restore

Use backup instead of restore to collect the original unit and a diff without replacing the newly installed vendor file. Long term, custom settings should be moved to /etc/systemd/system/postgresql.service.d/override.conf.

The option values are available with Tab completion:

steamroller update ORION-LAB --host velora-db-a01.ops.example \
  --preserve-postgresql-unit <TAB><TAB>
# backup  restore

restore is deliberately explicit. SteamRoller restores the file only when RPM verification identifies it as locally modified (or when the file is not owned by an RPM). It verifies the restored checksum, reloads systemd, validates the unit, and reports a failure if any of those checks fail. It does not restart the database service.

Reports

Source checkouts store reports beneath:

reports/SERVER_NAME/RUN_ID/

Precheck evidence includes precheck.txt, summary.json, checks.json, filesystem, mount, kernel, network, repository, Satellite, systemd, update, and PostgreSQL details. Update runs add the complete DNF transaction and postcheck; reboot runs preserve evidence before reboot and create a POST validation report after the host returns.

With PostgreSQL unit protection enabled, the update report also contains the unit before and after DNF, metadata, systemctl cat evidence, a unified diff, and—when requested—the restored unit.

List runs with:

steamroller status

Configuration and security

• global defaults: config/steamroller.yml;
• inventories: inventories/ENVIRONMENT/hosts.yml;
• optional environment settings: inventories/ENVIRONMENT/steamroller.yml;
• managed SSH profiles: ssh-keys/PROFILE/PRIVATE_KEY;
• real inventories, reports, backups, and private keys are excluded from Git;
• SSH host-key checking remains enabled;
• repository files are never moved without an explicit operator option.

Display effective settings with:

steamroller config ENVIRONMENT

Default uptime thresholds are 30 days for WARNING, 90 days for HIGH WARNING, and 200 days for CRITICAL WARNING. From the first warning threshold, precheck reports include a complete suggested reboot command.

Documentation

• Complete command HOWTO
• Project status
• Version 0.3.3 release notes
• Version 0.3.2 release notes
• Version 0.3.1 release notes
• Version 0.3.0 release notes
• Version 0.2.0 release notes
• Manual setup utilities

Planned installed layout

/opt/steamroller/                    application code
/etc/steamroller/                    configuration
/etc/steamroller/inventories/        inventories
/etc/steamroller/ssh-keys/           managed SSH identities
/var/lib/steamroller/reports/        persistent evidence
/var/log/steamroller/                operational logs
/usr/bin/steamroller                 operator entry point

RPM production and installation validation remain deferred until the source-based 0.3 series is accepted on real customer systems.

License

Copyright (C) 2026 markhawks and SteamRoller contributors.

SteamRoller is free software licensed under the GNU Affero General Public License, version 3 or any later version (AGPL-3.0-or-later). It is distributed without warranty. See LICENSE for the complete terms.