Syscare — Linux System Maintenance Tool

Syscare is a modular Bash-based system maintenance agent for Ubuntu Linux. It is designed to be reliable, automated and machine-freindly, with optional centralized reporting.

Syscare provides:

• System health checks (CPU, memory, disk)
• Safe cleanup of old logs and reports
• Automated backups with retention
• Structured JSON reports
• Optional systemd automation
• Optional Node.js backend for centralized report collection.

---

Features

• Modular architecture: health, cleanup, backup
• Configurable thresholds via /etc/syscare/syscare.conf
• JSON output for automation and backend integration
• Supports development mode (repo) and installed mode
• Systemd service and timer for scheduled execution
• Optional backend with failure-safe reporting

---

Project Structure

.
├── backups/             # Backups generated by syscare
├── config/
│   └── syscare.conf     # Configuration file
├── lib/
│   ├── backup.sh
│   ├── cleanup.sh
│   ├── health.sh
│   └── utils.sh
├── logs/
├── reports/
├── syscare.sh           # Main CLI entrypoint
├── install.sh           # Agent installer
├── uninstall.sh         # Agent uninstaller
├── syscare-backend/     # Optional Node.js backend API
├── install-backend.sh
├── uninstall-backend.sh
├── README.md
└── out.json             # Latest JSON report (optional)

---

Installation

Clone the repository:

git clone https://github.com/Sanjeeban14/syscare.git
cd syscare

Install syscare system-wide:

sudo ./install.sh

This will:

• Create system directories:

/usr/local/lib/syscare       # code
/etc/syscare                 # config
/var/log/syscare             # logs
/var/lib/syscare             # runtime data / backups
/usr/local/bin/syscare       # global CLI wrapper

• Copy code (lib/, syscare.sh) to /usr/local/lib/syscare
• Copy config to /etc/syscare/syscare.conf
• Install a global wrapper /usr/local/bin/syscare for easy execution

---

Quick Start

# Enable and start daily systemd timer
sudo systemctl daemon-reload
sudo systemctl enable --now syscare.timer

# Verify the timer is active
systemctl list-timers | grep syscare

# Run manually if desired
syscare all | jq .

---

Usage

syscare check             # Run health checks
syscare cleanup           # Run cleanup (dry-run by default)
syscare cleanup --apply   # Apply cleanup (delete files)
syscare backup            # Run backup with retention
syscare all               # Run all modules and emit JSON report

Example JSON output:

{
  "timestamp": "2025-12-31T00:45:00+05:30",
  "health": {
    "cpu": {"status": "ok", "load_1m": "0.5", "threshold": "1.0"},
    "memory": {"status": "ok", "usage_percent": 45, "threshold": 80},
    "disk": {"status": "ok", "threshold": 85}
  },
  "cleanup": {
    "status": "ok",
    "deleted_files": 0,
    "dry_run": true,
    "days": 7
  },
  "backup": {
    "status": "ok",
    "archive": "backup-2025-12-30T20:29:10+05:30.tar.gz",
    "retention_count": 5
  }
}

Tip: Pipe JSON output to jq for readability:

syscare all | jq .

---

Configuration

Default configuration file: /etc/syscare/syscare.conf

# CPU, memory, disk thresholds
CPU_THRESHOLD=1.0
MEMORY_THRESHOLD=80
DISK_THRESHOLD=85

# Cleanup
CLEANUP_DAYS=7

# Backup retention
RETENTION_COUNT=5

• Can override thresholds via CLI options:

syscare all --cpu-threshold=0.8 --memory-threshold=75

---

Systemd Integration

Syscare can run automatically using systemd timer.

  sudo systemctl enable --now syscare.timer

• JSON reports are logged to journald or /var/log/syscare/syscare.log View logs (journald)

journalctl -u syscare.service

Follow logs live:

journalctl -u syscare.service -f

Tip: For testing, you can set OnUnitActiveSec=20s in the timer and reset to 1d for daily execution later.

Do this after every change:

sudo systemctl daemon-reload
sudo systemctl restart syscare.timer

---

Backend Integration (Optional)

Syscare can send its JSON reports to a central backend server.

The backend is a Node.js + Express REST API that accepts reports via HTTP.

Backend Features

• REST API (/api/health)
• Health endpoint (/api/health)
• Stores JSON reports on disk
• Designed to run as a systemd service

Backend Installation

From the syscare repo root:

chmod +x install-backend.sh
./install-backend.sh

This wil:

• Verify Node.js(>=18)
• Optionally install/upgrade Node.js with user content
• Install backend dependencies
• Install and register syscare-backend.service

Enable backend:

sudo systemctl enable --now syscare-backend.service

Verify backend health:

curl http://localhost:3000/api/health

Expected output:

{ "status": "ok" }

Backend Configuration

BACKEND_ENABLED=true
BACKEND_URL="http://localhost:3000/api/reports"
BACKEND_HEALTH_URL="http://localhost:3000/api/health"

Sending Reports from Syscare

When backend reporting is enabled, syscare sends its final JSON report automatically at the end of execution.

No changes to core syscare commands are required.

Retry Queue (Failure-Safe Reporting)

Backend reporting in syscare is best-effort and non-blocking

If the backend is unavialable (network down, service stopped, etc):

• JSON reports are queued locally in pending directory.
• Core syscare operations (health, cleanup, backup) still complete successfully.
• Pending reports are retried automatically on the next successful run.

This design ensures system maintainance never depends on backend availability.

---

Development Mode

• Run directly from repo without installing:

./syscare.sh all

Outputs are written to local logs/, backups/, and reports/.

---

Uninstall

Remove Syscare Agent

chmod 755 uninstall.sh
./uninstall.sh

or (minimally)

chmod +rx uninstall.sh
./uninstall.sh

Removes syscare binaries, configs, logs, backups, and systemd units.

Remove Syscare Backend

chmod 755 uninstall-backend.sh
./uninstall-backend.sh

or (minimally)

chmod +rx uninstall-backend.sh
./uninstall-backend.sh

Removes backend service, data and logs.

Node.js is not affected.

---

Future Enhancements

• Backend enhancements: alerts, authentication, dashboards
• Alerts & notifications: e.g., email if thresholds are exceeded
• Packaging as .deb or .rpm for easier installation
• Hardening and security improvements

---

License

MIT License — free to use, modify, and share.

---

✅ Summary

Syscare is a reliability-focused Linux maintenance agent with:

• Modular bash design
• Structured JSON output
• systemd automation
• Optional, failure-safe backend reporting

Designed for real systems, not demos.

---