Echo
65cfb40abb
Some checks failed
CI/CD Pipeline / Code Format (push) Has been cancelled
CI/CD Pipeline / Clippy Lints (push) Has been cancelled
CI/CD Pipeline / Unit Tests (push) Has been cancelled
CI/CD Pipeline / Security Audit (push) Has been cancelled
CI/CD Pipeline / Build Release (x86_64-unknown-linux-gnu) (push) Has been cancelled
CI/CD Pipeline / Build Ubuntu Package (push) Has been cancelled
Phase 2: Core API Development - 15 REST API endpoints (packages, patches, system, jobs, websocket) - mTLS authentication layer (src/auth/mtls.rs) - IP whitelist enforcement (src/auth/whitelist.rs) - Job manager with async operation support - WebSocket streaming for job status Phase 3: Security Hardening - Security testing: 16/16 tests passing - Fuzz testing: 21 tests, all findings resolved - Threat model validation (STRIDE matrix) - TLS binding fix (critical vulnerability resolved) - Security documentation complete Phase 4: Production Readiness - Performance benchmarking (all targets met) - Package creation (.deb/.rpm structures) - Documentation (README, API docs, deployment guide) - Security hardening (6 vulnerabilities fixed) Deliverables: - API_DOCUMENTATION.md (889 lines) - DEPLOYMENT_GUIDE.md (733 lines) - SECURITY.md (346 lines) - README.md (525 lines) - debian/ package structure - linux-patch-api.spec (RPM) - install.sh installer script - benches/api_benchmarks.rs - Multiple security/performance reports Security Status: 0 vulnerabilities remaining Test Coverage: 31 unit tests, 21 integration tests Build Status: Release optimized
396 lines
8.7 KiB
Markdown
396 lines
8.7 KiB
Markdown
# Linux Patch API - Package Build Guide
|
|
|
|
This document provides comprehensive instructions for building production-ready Debian (.deb) and RPM (.rpm) packages for the Linux Patch API.
|
|
|
|
## Prerequisites
|
|
|
|
### For Debian Package Building
|
|
|
|
```bash
|
|
# Install required tools
|
|
apt-get update
|
|
apt-get install -y \
|
|
cargo \
|
|
rustc \
|
|
debhelper \
|
|
pkg-config \
|
|
libsystemd-dev \
|
|
dpkg-dev \
|
|
fakeroot
|
|
```
|
|
|
|
### For RPM Package Building
|
|
|
|
```bash
|
|
# Install required tools (RHEL/CentOS/Fedora)
|
|
dnf install -y \
|
|
cargo \
|
|
rust \
|
|
rpm-build \
|
|
rpmdevtools \
|
|
systemd-rpm-macros \
|
|
pkgconfig \
|
|
systemd-devel \
|
|
gcc
|
|
|
|
# Or on Ubuntu/Debian for cross-building
|
|
apt-get install -y \
|
|
cargo \
|
|
rustc \
|
|
rpm \
|
|
rpmbuild \
|
|
libsystemd-dev
|
|
```
|
|
|
|
## Building Debian Package (.deb)
|
|
|
|
### Quick Build
|
|
|
|
```bash
|
|
cd /a0/usr/projects/linux_patch_api
|
|
|
|
# Build release binary
|
|
cargo build --release --target x86_64-unknown-linux-gnu
|
|
|
|
# Build Debian package
|
|
dpkg-buildpackage -us -uc -b
|
|
|
|
# Package will be created in parent directory
|
|
# linux-patch-api_1.0.0-1_amd64.deb
|
|
```
|
|
|
|
### Detailed Build Process
|
|
|
|
```bash
|
|
# 1. Ensure release binary exists
|
|
cargo build --release --target x86_64-unknown-linux-gnu
|
|
|
|
# 2. Verify debian/ directory structure
|
|
ls -la debian/
|
|
# Should contain: control, rules, changelog, compat, install, conffiles, copyright
|
|
# And maintainer scripts: preinst, postinst, prerm, postrm
|
|
|
|
# 3. Build the package
|
|
dpkg-buildpackage -us -uc -b
|
|
|
|
# 4. Verify package contents
|
|
dpkg-deb --contents ../linux-patch-api_1.0.0-1_amd64.deb
|
|
|
|
# 5. Verify package info
|
|
dpkg-deb --info ../linux-patch-api_1.0.0-1_amd64.deb
|
|
|
|
# 6. Lint the package (optional but recommended)
|
|
lintian ../linux-patch-api_1.0.0-1_amd64.deb
|
|
```
|
|
|
|
### Installation Test
|
|
|
|
```bash
|
|
# Install the package
|
|
dpkg -i linux-patch-api_1.0.0-1_amd64.deb
|
|
|
|
# Verify installation
|
|
systemctl status linux-patch-api
|
|
linux-patch-api --version
|
|
|
|
# Check installed files
|
|
dpkg -L linux-patch-api
|
|
|
|
# Remove package (keeping configs)
|
|
dpkg -r linux-patch-api
|
|
|
|
# Purge package (removing all configs)
|
|
dpkg -P linux-patch-api
|
|
```
|
|
|
|
## Building RPM Package (.rpm)
|
|
|
|
### Quick Build
|
|
|
|
```bash
|
|
cd /a0/usr/projects/linux_patch_api
|
|
|
|
# Build release binary
|
|
cargo build --release --target x86_64-unknown-linux-gnu
|
|
|
|
# Build RPM package
|
|
rpmbuild -ba linux-patch-api.spec
|
|
|
|
# Package will be created in ~/rpmbuild/RPMS/
|
|
```
|
|
|
|
### Detailed Build Process
|
|
|
|
```bash
|
|
# 1. Set up RPM build environment
|
|
rpmdev-setuptree
|
|
|
|
# 2. Copy spec file to SPECS directory
|
|
cp linux-patch-api.spec ~/rpmbuild/SPECS/
|
|
|
|
# 3. Copy source tarball to SOURCES directory
|
|
# Create source tarball
|
|
tar -czvf linux-patch-api-1.0.0.tar.gz \
|
|
--exclude=target \
|
|
--exclude=.git \
|
|
--exclude=debian \
|
|
--exclude=*.deb \
|
|
--exclude=*.rpm \
|
|
.
|
|
|
|
mv linux-patch-api-1.0.0.tar.gz ~/rpmbuild/SOURCES/
|
|
|
|
# 4. Build the RPM
|
|
rpmbuild -ba ~/rpmbuild/SPECS/linux-patch-api.spec
|
|
|
|
# 5. Verify RPM contents
|
|
rpm -qlp ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm
|
|
|
|
# 6. Verify RPM info
|
|
rpm -qip ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm
|
|
|
|
# 7. Lint the spec file (optional but recommended)
|
|
rpmlint ~/rpmbuild/SPECS/linux-patch-api.spec
|
|
```
|
|
|
|
### Installation Test
|
|
|
|
```bash
|
|
# Install the RPM
|
|
rpm -ivh ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm
|
|
|
|
# Or using dnf/yum
|
|
dnf install ~/rpmbuild/RPMS/x86_64/linux-patch-api-1.0.0-1.el9.x86_64.rpm
|
|
|
|
# Verify installation
|
|
systemctl status linux-patch-api
|
|
linux-patch-api --version
|
|
|
|
# List installed files
|
|
rpm -ql linux-patch-api
|
|
|
|
# Remove package
|
|
rpm -e linux-patch-api
|
|
```
|
|
|
|
## Using the Interactive Installer
|
|
|
|
For manual deployment without package managers:
|
|
|
|
```bash
|
|
# Ensure binary is built
|
|
cargo build --release --target x86_64-unknown-linux-gnu
|
|
|
|
# Run installer (must be root)
|
|
sudo ./install.sh
|
|
```
|
|
|
|
The installer will:
|
|
1. Detect operating system
|
|
2. Check prerequisites (systemd, binary)
|
|
3. Create system user and group
|
|
4. Create directory structure
|
|
5. Install binary and configuration files
|
|
6. Install systemd service
|
|
7. Optionally generate self-signed certificates
|
|
8. Optionally enable and start the service
|
|
|
|
## Package Contents
|
|
|
|
### Installed Files
|
|
|
|
| Path | Description | Permissions |
|
|
|------|-------------|-------------|
|
|
| `/usr/bin/linux-patch-api` | Main binary | 755 |
|
|
| `/lib/systemd/system/linux-patch-api.service` | Systemd service unit | 644 |
|
|
| `/etc/linux_patch_api/config.yaml` | Main configuration | 640 |
|
|
| `/etc/linux_patch_api/whitelist.yaml` | IP whitelist | 640 |
|
|
| `/etc/linux_patch_api/certs/` | TLS certificates directory | 750 |
|
|
| `/var/lib/linux_patch_api/` | Data directory | 755 |
|
|
| `/var/log/linux_patch_api/` | Log directory | 755 |
|
|
|
|
### System User/Group
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| User | linux-patch-api |
|
|
| Group | linux-patch-api |
|
|
| Home | /var/lib/linux_patch_api |
|
|
| Shell | /usr/sbin/nologin |
|
|
| Type | System account |
|
|
|
|
## Supported Distributions
|
|
|
|
### Debian Package (.deb)
|
|
|
|
| Distribution | Versions | Status |
|
|
|--------------|----------|--------|
|
|
| Debian | 11 (Bullseye), 12 (Bookworm) | ✅ Supported |
|
|
| Ubuntu | 20.04 LTS (Focal) | ✅ Supported |
|
|
| Ubuntu | 22.04 LTS (Jammy) | ✅ Supported |
|
|
| Ubuntu | 24.04 LTS (Noble) | ✅ Supported |
|
|
|
|
### RPM Package (.rpm)
|
|
|
|
| Distribution | Versions | Status |
|
|
|--------------|----------|--------|
|
|
| RHEL | 8, 9 | ✅ Supported |
|
|
| CentOS | 8, 9 | ✅ Supported |
|
|
| Fedora | 38+ | ✅ Supported |
|
|
| AlmaLinux | 8, 9 | ✅ Supported |
|
|
| Rocky Linux | 8, 9 | ✅ Supported |
|
|
|
|
## Troubleshooting
|
|
|
|
### Debian Package Issues
|
|
|
|
**Error: `dh_auto_install: error: ...`**
|
|
```bash
|
|
# Ensure release binary exists
|
|
ls -la target/x86_64-unknown-linux-gnu/release/linux-patch-api
|
|
|
|
# Rebuild if missing
|
|
cargo build --release --target x86_64-unknown-linux-gnu
|
|
```
|
|
|
|
**Error: `missing build-dependency`**
|
|
```bash
|
|
# Install missing dependencies
|
|
apt-get install -y libsystemd-dev pkg-config
|
|
```
|
|
|
|
### RPM Package Issues
|
|
|
|
**Error: `RPMS not found`**
|
|
```bash
|
|
# Check build output
|
|
ls -la ~/rpmbuild/RPMS/x86_64/
|
|
|
|
# Check for build errors
|
|
cat ~/rpmbuild/BUILDROOT/*/var/log/rpmbuild.log
|
|
```
|
|
|
|
**Error: `missing BuildRequires`**
|
|
```bash
|
|
# Install development packages
|
|
dnf install -y systemd-devel pkgconfig
|
|
```
|
|
|
|
### Service Issues
|
|
|
|
**Service fails to start:**
|
|
```bash
|
|
# Check service status
|
|
systemctl status linux-patch-api
|
|
|
|
# View logs
|
|
journalctl -u linux-patch-api -f
|
|
|
|
# Check configuration
|
|
linux-patch-api --config /etc/linux_patch_api/config.yaml --check
|
|
|
|
# Verify certificates
|
|
ls -la /etc/linux_patch_api/certs/
|
|
```
|
|
|
|
## CI/CD Integration
|
|
|
|
### GitHub Actions Example
|
|
|
|
```yaml
|
|
name: Build Packages
|
|
|
|
on:
|
|
release:
|
|
types: [published]
|
|
|
|
jobs:
|
|
build-deb:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Install dependencies
|
|
run: |
|
|
sudo apt-get update
|
|
sudo apt-get install -y cargo debhelper pkg-config libsystemd-dev
|
|
|
|
- name: Build release
|
|
run: cargo build --release
|
|
|
|
- name: Build Debian package
|
|
run: dpkg-buildpackage -us -uc -b
|
|
|
|
- name: Upload artifact
|
|
uses: actions/upload-artifact@v4
|
|
with:
|
|
name: linux-patch-api-deb
|
|
path: ../linux-patch-api_*.deb
|
|
|
|
build-rpm:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v4
|
|
|
|
- name: Install dependencies
|
|
run: |
|
|
sudo apt-get update
|
|
sudo apt-get install -y cargo rpm rpmbuild
|
|
|
|
- name: Set up RPM environment
|
|
run: rpmdev-setuptree
|
|
|
|
- name: Build release
|
|
run: cargo build --release
|
|
|
|
- name: Build RPM package
|
|
run: rpmbuild -ba linux-patch-api.spec
|
|
|
|
- name: Upload artifact
|
|
uses: actions/upload-artifact@v4
|
|
with:
|
|
name: linux-patch-api-rpm
|
|
path: ~/rpmbuild/RPMS/x86_64/*.rpm
|
|
```
|
|
|
|
## Version Management
|
|
|
|
### Updating Version for New Release
|
|
|
|
1. **Update Cargo.toml:**
|
|
```toml
|
|
[package]
|
|
version = "1.0.1" # Increment version
|
|
```
|
|
|
|
2. **Update debian/changelog:**
|
|
```bash
|
|
dch -v 1.0.1-1 "Release notes here"
|
|
```
|
|
|
|
3. **Update RPM spec:**
|
|
```spec
|
|
Version: 1.0.1
|
|
Release: 1%{?dist}
|
|
```
|
|
|
|
4. **Update ROADMAP.md:**
|
|
- Mark previous version complete
|
|
- Add new version to changelog
|
|
|
|
## Security Considerations
|
|
|
|
- Packages are signed with maintainer GPG key for production deployments
|
|
- All maintainer scripts run with `set -e` for fail-fast behavior
|
|
- Configuration files are marked as conffiles to preserve user modifications
|
|
- System user has minimal privileges (nologin shell, no home directory)
|
|
- Directory permissions follow principle of least privilege
|
|
- TLS certificates should be replaced with CA-signed certs in production
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
- Review logs: `journalctl -u linux-patch-api -f`
|
|
- Check documentation: `/usr/share/doc/linux-patch-api/`
|
|
- Report issues: https://gitea.moon-dragon.us/echo/linux_patch_api/issues
|