🛠️ SYSMAINT

Enterprise Linux System Maintenance — One Command, All Distros

Automated Package Updates • System Cleanup • Security Auditing • Performance Optimization

Supports Ubuntu, Debian, Fedora, RHEL, Rocky, Alma, CentOS, Arch, openSUSE

📖 Table of Contents

Quick Start
Product Requirements
Why SYSMAINT
Features
Platform Support
Installation
Usage
Automation
Documentation
Quality Metrics
Contributing
License

🚀 Quick Start

# Clone the repository
git clone https://github.com/Harery/SYSMAINT.git
cd SYSMAINT

# Make executable
chmod +x sysmaint

# Preview changes (100% safe, read-only)
sudo ./sysmaint --dry-run

# Execute maintenance
sudo ./sysmaint

Or use Docker:

docker run --rm --privileged ghcr.io/harery/sysmaint:latest

📋 Product Requirements

The SYSMAINT product requirements document (PRD) defines the vision, requirements, and roadmap for the project.

📄 View Product Requirements (PRD)

Key Requirements

Multi-Distro Support - Single tool supporting 9+ Linux distributions
Safe Operation - Dry-run mode for previewing all changes
Audit Trail - JSON output for compliance and monitoring
Automation Ready - Systemd timers, cron jobs, Docker/Kubernetes support
Enterprise Grade - Comprehensive testing (500+ tests), security scanning

✨ Why SYSMAINT?

Linux system maintenance is fragmented across distributions, each with different package managers, cleanup procedures, and security practices. SYSMAINT unifies这一切 into a single, production-ready tool.

Feature	SYSMAINT	Traditional Scripts
9 Distros	✅ One tool	❌ Multiple scripts
Safety	✅ Dry-run mode	❌ Risky execution
Audit Trail	✅ JSON output	❌ No logging
Interactive	✅ TUI menu	❌ CLI only
Tests	✅ 500+ tests	❌ None
Speed	⚡ <3.5 min avg	🐌 Variable

📦 Features

Core Capabilities

graph LR
    A[sysmaint] --> B[Package Management]
    A --> C[System Cleanup]
    A --> D[Security Auditing]
    A --> E[Performance Optimization]

    B --> B1[apt/dnf/pacman/zypper]
    B --> B2[snap packages]
    B --> B3[flatpak packages]

    C --> C1[Log rotation]
    C --> C2[Cache cleanup]
    C --> C3[Old kernel removal]

    D --> D1[SSH configuration]
    D --> D2[Firewall status]
    D --> D3[Service validation]

    E --> E1[Disk recovery reporting]
    E --> E2[JSON telemetry]

What SYSMAINT Does

Module	Description	Benefit
Package Management	Automated updates, upgrades, and cleanup	Keeps software current & secure
System Cleanup	Removes logs, caches, temp files, old kernels	Recovers disk space
Security Auditing	Checks permissions, services, and repos	Identifies vulnerabilities
JSON Telemetry	Structured output for monitoring	Enables automation
Dry-Run Mode	Preview all changes safely	Zero-risk testing
Interactive TUI	User-friendly dialog-based menu	Easy for beginners

🌍 Platform Support

Distribution	Versions	Package Manager	Status
Ubuntu	22.04, 24.04	`apt`	✅ LTS
Debian	12, 13	`apt`	✅ Stable
Fedora	41	`dnf`	✅ Latest
RHEL	9, 10	`dnf/yum`	✅ Enterprise
Rocky Linux	9, 10	`dnf/yum`	✅ Enterprise
AlmaLinux	9, 10	`dnf/yum`	✅ Enterprise
CentOS	9 Stream	`dnf/yum`	✅ Stream
Arch Linux	Rolling	`pacman`	✅ Tested
openSUSE	Tumbleweed	`zypper`	✅ Tested

📥 Installation

Method 1: Git Clone (Recommended)

git clone https://github.com/Harery/SYSMAINT.git
cd SYSMAINT
chmod +x sysmaint
sudo ./sysmaint --dry-run

Method 2: Direct Download

curl -O https://raw.githubusercontent.com/Harery/SYSMAINT/main/sysmaint
chmod +x sysmaint
sudo ./sysmaint --dry-run

Method 3: Docker

docker pull ghcr.io/harery/sysmaint:latest
docker run --rm --privileged ghcr.io/harery/sysmaint:latest

Available Docker Images:

Image	Description
`ghcr.io/harery/sysmaint:latest`	Latest stable release
`ghcr.io/harery/sysmaint:v1.0.0`	Version pinned
`ghcr.io/harery/sysmaint:ubuntu`	Ubuntu-based variant
`ghcr.io/harery/sysmaint:debian`	Debian-based variant
`ghcr.io/harery/sysmaint:fedora`	Fedora-based variant

Multi-architecture: linux/amd64, linux/arm64

🐳 Full Docker Guide: docs/DOCKER.md

Method 4: System-Wide Installation

# Install to system path
sudo install -Dm755 sysmaint /usr/local/sbin/sysmaint

# Enable automated maintenance
sudo install -Dm644 packaging/systemd/sysmaint.{service,timer} /etc/systemd/system/
sudo systemctl enable --now sysmaint.timer

📖 Full Installation Guide: docs/INSTALLATION.md

💻 Usage

Interactive Mode (Recommended for First-Time Users)

sudo ./sysmaint --gui

Launches an interactive terminal menu (TUI) for guided operation.

Fully Automated Mode

sudo ./sysmaint --auto

Runs all maintenance operations without prompts.

Specific Operations

# Package management only
sudo ./sysmaint --upgrade

# Cleanup only
sudo ./sysmaint --cleanup

# Remove old kernels
sudo ./sysmaint --purge-kernels

# Security audit only
sudo ./sysmaint --security-audit

JSON Output for Automation

sudo ./sysmaint --json-summary | jq .

Quiet Mode (for Cron)

sudo ./sysmaint --auto --quiet

All Command-Line Options

Option	Description
`--dry-run`	Preview changes without executing
`--gui`	Interactive TUI menu
`--auto`	Non-interactive automated mode
`--upgrade`	Update all packages
`--cleanup`	Clean caches and temp files
`--purge-kernels`	Remove old kernel packages
`--security-audit`	Run security checks
`--json-summary`	Output results in JSON format
`--verbose`	Detailed logging output
`--quiet`	Minimal output only

🤖 Automation

Systemd Timer (Recommended)

# Install service files
sudo install -Dm755 sysmaint /usr/local/sbin/sysmaint
sudo install -Dm644 packaging/systemd/sysmaint.{service,timer} /etc/systemd/system/

# Enable weekly automatic maintenance
sudo systemctl enable --now sysmaint.timer

# Check status
sudo systemctl status sysmaint.timer

Cron Job

# Edit crontab
crontab -e

# Add weekly maintenance (Sundays at 2 AM)
0 2 * * 0 /usr/local/sbin/sysmaint --auto --quiet

Docker Compose

services:
  sysmaint:
    image: ghcr.io/harery/sysmaint:latest
    privileged: true
    volumes:
      - /:/host:ro
    # Override command as needed
    # command: ["--auto", "--quiet"]

Kubernetes CronJob

apiVersion: batch/v1
kind: CronJob
metadata:
  name: sysmaint
spec:
  schedule: "0 2 * * 0"  # Weekly at 2 AM
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: sysmaint
            image: ghcr.io/harery/sysmaint:latest
            securityContext:
              privileged: true
          restartPolicy: OnFailure

📊 Quality Metrics

Metric	Value	Status
Test Coverage	500+ tests across 14 suites	✅
Code Quality	ShellCheck: 0 errors	✅
Runtime	<3.5 minutes average	✅
Memory Usage	<50 MB	✅
Platform Support	9 distributions tested	✅
Container Images	Multi-arch (amd64/arm64)	✅

🔒 Security

SYSMAINT is built with security-first principles:

✅ Input Validation — All parameters sanitized
✅ Least Privilege — Minimal sudo requirements
✅ Audit Trail — JSON output for compliance
✅ No External Calls — Zero network dependencies
✅ ShellCheck Verified — Static analysis passed
✅ Vulnerability Scanning — CI/CD integrated

🔐 Security Policy: docs/SECURITY.md

🧪 Testing

SYSMAINT includes 500+ tests covering all supported Linux distributions with automated testing in both local Docker and GitHub Actions.

Quick Test Commands

# Quick validation on current system
./tests/quick_test.sh

# Test specific OS in Docker
./tests/test_single_os.sh ubuntu 24.04

# Validate before PR submission
./tests/validate_pr.sh

Test Coverage

Category	Suites	Tests
Smoke Tests	Basic functionality	10+
OS Family	Debian, RedHat, Arch, SUSE, Fedora, Cross-OS	80+
Execution Modes	--auto, --gui, --dry-run, --quiet, --verbose, --json	20+
Features	Packages, cleanup, security, firmware	60+
Security	Permissions, GPG, SELinux/AppArmor	40+
Edge Cases	Failures, network issues, permissions	30+
Integration	systemd, cron, Docker, services	30+
Docker	Container-specific tests	40+
GitHub Actions	CI/CD environment tests	50+
Performance	Benchmarks	15+
TOTAL	14 Suites	500+

Local Docker Testing

Test across all supported OS locally:

# Single OS
./tests/run_local_docker_tests.sh --os ubuntu-24

# Multiple OS (parallel)
./tests/run_local_docker_tests.sh --os ubuntu-24,debian-12,fedora-41 --parallel

# Full test suite
./tests/full_test.sh --profile full --parallel

GitHub Actions CI/CD

Automatic: Runs on every push and pull request
Matrix: Tests all 14 OS versions in parallel
Fast: Smoke tests complete in ~5 minutes per OS

# Trigger manual CI run
gh workflow run test-matrix.yml -f test_profile=smoke -f os_filter=ubuntu-24

# Download CI results
gh run download --name test-results-ubuntu-24

Result Comparison

Compare local Docker vs GitHub Actions results to identify discrepancies:

# Run both and compare
./tests/run_dual_environment_tests.sh --os ubuntu --version 24.04

# Compare existing results
./tests/report_discrepancies.sh --results tests/results

Metrics:

Pass Rate: Tests passed percentage
Congruence: Environment similarity (0-100%)
Accuracy Score: Overall consistency measure

Test Documentation

Document	Description
Test Dashboard	Interactive test results visualization
Test Quick Start	Get started in 5 minutes
Test Guide	Comprehensive testing guide
Test Cheatsheet	Quick command reference
Test Matrix	Complete 500+ test inventory
Test Summary	Infrastructure overview
Test Architecture	Test structure & design
Test Troubleshooting	Common issues & solutions
Contributing Tests	Contribution guide
OS Support	OS compatibility matrix
Performance Baselines	Performance targets & metrics
Status Assessment	Project completion status
Executive Summary	Executive overview

📖 Documentation

Document	Description
Product Requirements (PRD)	Product vision, requirements & roadmap
Project Structure	Directory organization & file layout
Library Modules	Core library documentation
Utility Scripts	Development & CI/CD scripts
Installation Guide	All installation methods
Troubleshooting	Common issues & solutions
Architecture	System design & components
Performance	Benchmarks by OS
Security	Security policy & best practices
Contributing	Development guidelines
Code of Conduct	Community guidelines

🤝 Contributing

We welcome contributions from the community! Please see our contributing guidelines:

Contributing Guide — Development workflow & standards
Code of Conduct — Community guidelines

📜 License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Star History

If you find SYSMAINT useful, please consider giving it a star! ⭐

🔗 Quick Links

Resource	Link
Website	https://www.harery.com
Repository	https://github.com/Harery/SYSMAINT
Documentation	https://github.com/Harery/SYSMAINT/tree/main/docs
Issue Tracker	https://github.com/Harery/SYSMAINT/issues
Discussions	https://github.com/Harery/SYSMAINT/discussions
Releases	https://github.com/Harery/SYSMAINT/releases
Docker Image	https://ghcr.io/harery/sysmaint

Built with ❤️ for the Linux ecosystem

GitHub • Documentation • Support • Discussions

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github		.github
debian		debian
docker		docker
docs		docs
helm/sysmaint		helm/sysmaint
k8s		k8s
lib		lib
packaging		packaging
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
sysmaint		sysmaint

License

Harery/SYSMAINT

Folders and files

Latest commit

History

Repository files navigation

🛠️ SYSMAINT

Enterprise Linux System Maintenance — One Command, All Distros

📖 Table of Contents

🚀 Quick Start

📋 Product Requirements

Key Requirements

✨ Why SYSMAINT?

📦 Features

Core Capabilities

What SYSMAINT Does

🌍 Platform Support

📥 Installation

Method 1: Git Clone (Recommended)

Method 2: Direct Download

Method 3: Docker

Method 4: System-Wide Installation

💻 Usage

Interactive Mode (Recommended for First-Time Users)

Fully Automated Mode

Specific Operations

JSON Output for Automation

Quiet Mode (for Cron)

All Command-Line Options

🤖 Automation

Systemd Timer (Recommended)

Cron Job

Docker Compose

Kubernetes CronJob

📊 Quality Metrics

🔒 Security

🧪 Testing

Quick Test Commands

Test Coverage

Local Docker Testing

GitHub Actions CI/CD

Result Comparison

Test Documentation

📖 Documentation

🤝 Contributing

📜 License

Star History

🔗 Quick Links

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages

Packages