Echo
b822eb083d
Some checks failed
CI Pipeline / Rust Format Check (push) Successful in 4s
CI Pipeline / Clippy Lints (push) Successful in 45s
CI Pipeline / Rust Unit Tests (push) Successful in 1m3s
CI Pipeline / Security Audit (push) Successful in 4s
CI Pipeline / Frontend Lint & Type Check (push) Successful in 12s
CI Pipeline / Build .deb & Release (push) Has been cancelled
243 lines
6.8 KiB
Markdown
243 lines
6.8 KiB
Markdown
# Linux Patch Manager
|
|
|
|
**Enterprise-class secure web-based management interface for controlling patching and updates on Linux servers and workstations.**
|
|
|
|
## Overview
|
|
|
|
Linux Patch Manager provides a centralized web interface to manage patching and software updates across a fleet of Linux servers and workstations. It communicates with managed devices through the [Linux Patch API](https://gitea.moon-dragon.us/echo/linux_patch_api), leveraging mTLS-secured RESTful endpoints for all operations.
|
|
|
|
## Key Features
|
|
|
|
- **Centralized Dashboard** — Monitor patch status across all managed hosts from a single interface
|
|
- **Multi-Distribution Support** — Manage Debian/Ubuntu, RHEL/CentOS/Fedora, Alpine, and Arch hosts
|
|
- **Secure by Design** — mTLS authentication, role-based access control, audit logging
|
|
- **Batch Operations** — Apply patches and updates across multiple hosts simultaneously
|
|
- **Scheduling** — Plan and schedule patch windows with approval workflows
|
|
- **Reporting** — Compliance reporting and patch status dashboards
|
|
|
|
## Architecture
|
|
|
|
Linux Patch Manager is a web application that acts as a management plane, communicating with the Linux Patch API agent running on each managed host.
|
|
|
|
```
|
|
┌─────────────────────┐
|
|
│ Linux Patch Manager │ ← Web UI (this project)
|
|
│ (Management Plane) │
|
|
└──────────┬──────────┘
|
|
│ mTLS / REST API
|
|
┌──────┼──────┐
|
|
▼ ▼ ▼
|
|
┌──────┐┌──────┐┌──────┐
|
|
│ Host ││ Host ││ Host │ ← Linux Patch API agents
|
|
│ A ││ B ││ C │
|
|
└──────┘└──────┘└──────┘
|
|
```
|
|
|
|
## System Requirements
|
|
|
|
| Component | Requirement |
|
|
|-----------|-------------|
|
|
| **Operating System** | Ubuntu 22.04 LTS or 24.04 LTS |
|
|
| **Database** | PostgreSQL 16 (via official PostgreSQL repository) |
|
|
| **Memory** | 2 GB RAM minimum, 4 GB recommended |
|
|
| **Storage** | 1 GB for application + database space |
|
|
| **Network** | HTTPS access (port 443 recommended) |
|
|
|
|
## Installation
|
|
|
|
### 1. Download the Package
|
|
|
|
Download the latest `.deb` package from the [Gitea Releases](https://gitea-lxc.moon-dragon.us/echo/linux_patch_manager/releases) page:
|
|
|
|
```bash
|
|
wget https://gitea-lxc.moon-dragon.us/echo/linux_patch_manager/releases/download/v0.0.2/linux-patch-manager_1.0.0-1_amd64.deb
|
|
```
|
|
|
|
### 2. Install PostgreSQL 16
|
|
|
|
**Important:** PostgreSQL 16 is NOT available in Ubuntu's default repositories. You MUST add the official PostgreSQL repository.
|
|
|
|
```bash
|
|
# Add PostgreSQL official repository
|
|
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
|
|
|
|
# Import signing key
|
|
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
|
|
|
|
# Update package list
|
|
sudo apt update
|
|
|
|
# Install PostgreSQL 16 and SSL library
|
|
sudo apt install -y postgresql-16 libssl3
|
|
```
|
|
|
|
### 3. Install the Package
|
|
|
|
```bash
|
|
sudo dpkg -i linux-patch-manager_1.0.0-1_amd64.deb
|
|
```
|
|
|
|
Or with automatic dependency resolution:
|
|
|
|
```bash
|
|
sudo apt install ./linux-patch-manager_1.0.0-1_amd64.deb
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### 1. Database Setup
|
|
|
|
Create the PostgreSQL database and user:
|
|
|
|
```bash
|
|
sudo -u postgres psql <<EOF
|
|
CREATE DATABASE patch_manager;
|
|
CREATE USER patch_manager WITH PASSWORD 'your_secure_password';
|
|
GRANT ALL PRIVILEGES ON DATABASE patch_manager TO patch_manager;
|
|
\q
|
|
EOF
|
|
```
|
|
|
|
### 2. Configure the Application
|
|
|
|
Edit the configuration file:
|
|
|
|
```bash
|
|
sudo nano /etc/patch-manager/config.toml
|
|
```
|
|
|
|
Example configuration:
|
|
|
|
```toml
|
|
[database]
|
|
url = "postgresql://patch_manager:your_secure_password@localhost/patch_manager"
|
|
|
|
[server]
|
|
host = "0.0.0.0"
|
|
port = 8080
|
|
|
|
[security]
|
|
# Generate a secure key for session encryption
|
|
session_key = "generate-a-secure-random-key-here"
|
|
```
|
|
|
|
### 3. Run Database Migrations
|
|
|
|
```bash
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/001_initial_schema.sql
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/002_seed_admin.sql
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/003_jobs_scheduling.sql
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/004_maintenance_windows.sql
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/005_audit_hardening.sql
|
|
```
|
|
|
|
## Starting Services
|
|
|
|
### Start the Application
|
|
|
|
```bash
|
|
sudo systemctl enable --now patch-manager.target
|
|
```
|
|
|
|
### Verify Services are Running
|
|
|
|
```bash
|
|
systemctl status patch-manager-web
|
|
systemctl status patch-manager-worker
|
|
```
|
|
|
|
### Check Logs
|
|
|
|
```bash
|
|
journalctl -u patch-manager-web -f
|
|
journalctl -u patch-manager-worker -f
|
|
```
|
|
|
|
## Initial Access
|
|
|
|
1. Open a web browser and navigate to: `https://your-server-ip:8080`
|
|
|
|
2. Default admin credentials (change immediately!):
|
|
- **Username:** `admin`
|
|
- **Password:** Check the migration output or set during setup
|
|
|
|
3. Complete the initial setup wizard to configure:
|
|
- Admin password change
|
|
- MFA setup
|
|
- First host enrollment
|
|
|
|
## Building from Source
|
|
|
|
### Prerequisites
|
|
|
|
```bash
|
|
# Rust toolchain
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
source $HOME/.cargo/env
|
|
|
|
# Node.js 18+
|
|
sudo apt install -y nodejs npm
|
|
|
|
# Build dependencies
|
|
sudo apt install -y pkg-config libssl-dev postgresql-16
|
|
```
|
|
|
|
### Build the Package
|
|
|
|
```bash
|
|
cd /path/to/linux_patch_manager
|
|
chmod +x scripts/build-package.sh
|
|
./scripts/build-package.sh
|
|
```
|
|
|
|
The `.deb` package will be created in the project root directory.
|
|
|
|
## Documentation
|
|
|
|
| Document | Description |
|
|
|----------|-------------|
|
|
| [SPEC.md](SPEC.md) | Full project specification |
|
|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Architecture and design decisions |
|
|
| [REQUIREMENTS.md](REQUIREMENTS.md) | Functional and non-functional requirements |
|
|
| [docs/security-review.md](docs/security-review.md) | Security audit findings |
|
|
| [docs/runbooks/restore.md](docs/runbooks/restore.md) | Disaster recovery procedures |
|
|
|
|
## Related Projects
|
|
|
|
- **[Linux Patch API](https://gitea-lxc.moon-dragon.us/echo/linux_patch_api)** — The API agent that runs on each managed host
|
|
|
|
## Troubleshooting
|
|
|
|
### Services Won't Start
|
|
|
|
```bash
|
|
# Check configuration syntax
|
|
sudo patch-manager-web --validate-config
|
|
|
|
# Check database connectivity
|
|
sudo -u postgres psql -h localhost -U patch_manager patch_manager -c "SELECT 1"
|
|
|
|
# Check port availability
|
|
sudo ss -tlnp | grep 8080
|
|
```
|
|
|
|
### Database Migration Issues
|
|
|
|
```bash
|
|
# Check migration status
|
|
sudo -u postgres psql patch_manager -c "\dt"
|
|
|
|
# Re-run specific migration
|
|
sudo -u postgres psql patch_manager < /usr/share/patch-manager/migrations/001_initial_schema.sql
|
|
```
|
|
|
|
## License
|
|
|
|
Private — All rights reserved.
|
|
|
|
---
|
|
|
|
**Version:** 1.0.0-1
|
|
**Release:** v0.0.2
|
|
**Build Date:** 2026-04-28
|