jps-systemctl-utils 0.2.0

Collection of utils for systemctl related tasks

jps-systemctl-utils

A Python utility for automating systemctl service management operations with comprehensive logging and reporting.

🚀 Overview

jps-systemctl-utils provides a simple, sequential utility to manage systemd services in bulk. It automates the common workflow of checking status, stopping, starting, and verifying services, with full logging and detailed reports.

Features

• ✅ Bulk Service Management - Process multiple services from a simple text file
• 🔄 Automated Workflow - Runs status → stop → start → status for each service
• 📊 Progress Tracking - Real-time progress bar using Rich
• 📝 Comprehensive Logging - Dual logging to file (INFO) and stderr (WARNING+)
• 📋 Detailed Reports - Timestamped reports with all command outputs
• 🧪 Dry-run Mode - Test your workflow without executing commands
• ⚙️ Flexible Configuration - Custom output directories, log files, and reports
• 🎯 Comment Support - Skip comments and blank lines in service files

Use Cases

• Restarting multiple services after configuration changes
• Performing routine service maintenance
• Testing service restart procedures
• Documenting service states before/after operations
• Automating deployment workflows

📦 Installation

From Source

git clone https://github.com/jai-python3/jps-systemctl-utils.git
cd jps-systemctl-utils
make install

For Development

make install-dev-tools

🎯 Usage

Basic Usage

Create a file with service names (one per line):

# services.txt
nginx
apache2
mysql
postgresql

Run the utility:

jps-systemctl-utils-restart-services --infile services.txt

Dry-run Mode

Test without executing commands:

jps-systemctl-utils-restart-services --infile services.txt --dryrun

Custom Output Location

jps-systemctl-utils-restart-services --infile services.txt --outdir /var/log/service-ops

Full Control

jps-systemctl-utils-restart-services \
  --infile services.txt \
  --outdir /custom/output \
  --report-file /custom/report.txt \
  --logfile /custom/app.log \
  --dryrun

Example Output Structure

Default output location: /tmp/<username>/systemctl_runner/<timestamp>/

/tmp/myuser/systemctl_runner/2025-12-13-143000/
├── systemctl_runner_report.txt    # Detailed command outputs
└── systemctl_runner.log            # Application logs

Report Format

The generated report includes:

## method-created: /path/to/systemctl_runner.py
## date-created: 2025-12-13 14:30:00
## created-by: myuser
## logfile: /tmp/myuser/systemctl_runner/2025-12-13-143000/systemctl_runner.log
## infile: /path/to/services.txt

# Service: nginx
$ systemctl status nginx
● nginx.service - A high performance web server
   Loaded: loaded (/lib/systemd/system/nginx.service)
   Active: active (running)
(exit: 0)

$ systemctl stop nginx
(exit: 0)

$ systemctl start nginx
(exit: 0)

$ systemctl status nginx
● nginx.service - A high performance web server
   Active: active (running)
(exit: 0)

📚 API Documentation

Command-line Options

Option	Type	Required	Description
--infile	Path	Yes	Text file with newline-separated service names
--outdir	Path	No	Output directory for logs and reports
--report-file	Path	No	Custom path for the report file
--logfile	Path	No	Custom path for the log file
--dryrun	Flag	No	If set, no systemctl commands are executed

Input File Format

# Lines starting with # are comments
nginx
apache2

# Blank lines are ignored
mysql

🧪 Development

Running Tests

# Run all tests with coverage
make test

# Run specific test file
pytest tests/test_processor.py -v

# Run with detailed coverage report
pytest tests/ -v --cov=src/jps_systemctl_utils --cov-report=html

Code Quality

# Auto-fix code issues
make fix

# Format code with black
make format

# Run linting
make lint

# Run all quality checks
make fix && make format && make lint

Pre-commit Hooks

# Install pre-commit hooks
make precommit

Building and Publishing

# Build distribution packages
make build

# Check built packages
make check-build

# Publish to PyPI (with dry-run option)
make publish DRYRUN=1
make publish

🏗️ Project Structure

jps-systemctl-utils/
├── src/
│   └── jps_systemctl_utils/
│       ├── __init__.py           # Package version
│       ├── constants.py          # Logging constants
│       ├── logging_helper.py     # Logging configuration
│       ├── processor.py          # Core service processing logic
│       ├── report_writer.py      # Report generation
│       └── systemctl_runner.py   # CLI entry point
├── tests/
│   ├── conftest.py               # Shared fixtures
│   ├── test_constants.py         # Constants tests
│   ├── test_logging_helper.py    # Logging tests
│   ├── test_processor.py         # Processor tests
│   ├── test_report_writer.py     # Report writer tests
│   └── test_systemctl_runner.py  # CLI tests
├── pyproject.toml                # Project metadata
├── Makefile                      # Development commands
└── README.md                     # This file

🧩 Requirements

• Python 3.10+
• typer >= 0.12.3
• rich >= 13.0.0

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Run tests (make test)
4. Commit your changes (git commit -m 'Add some AmazingFeature')
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

📝 Changelog

See CHANGELOG.md for version history.

📄 License

MIT License © Jaideep Sundaram

🔗 Links

• Homepage
• Issue Tracker
• PyPI

⚠️ Disclaimer

This tool executes systemctl commands that affect system services. Always:

• Test with --dryrun first
• Review the service list carefully
• Have appropriate system permissions
• Back up important configurations
• Use in controlled environments