isp-status

Documents

isp-status -- Full System Rebuild Procedure

This document defines the deterministic rebuild process for isp-status on a fresh Ubuntu 24.x (headless) installation.

Philosophy

  • Repo = canonical truth
  • /etc = deployment artifact
  • No recursive ACLs on OS trust paths
  • Root performs system snapshot
  • ispstatus owns runtime + backup artifacts

Important Live Paths

These paths define the live Linux layout. Use them as the reference when restoring, troubleshooting, or comparing a Windows-hosted reconstruction of the system.

  • /opt/isp-status -- application code, templates, static assets, tools, Git checkout, and virtual environment.
  • /etc/isp-status -- host-specific private configuration such as flex700.env.
  • /etc/systemd/system -- active service and timer unit files.
  • /var/lib/isp-status -- persistent runtime state, including history.db, SQLite WAL/SHM files, spool data, bundles, and archive folders.
  • /var/log/isp-status -- application logs, troubleshooting logs, download logs, and update-import logs.
  • /run/isp-status -- volatile runtime state, including bgp.json.

The app currently listens on 172.16.198.26:8080; localhost checks are not expected to work unless the bind address is changed or a local proxy is added.

0. Base OS Assumptions

  • Ubuntu 24.x minimal install
  • Hostname configured
  • Network configured
  • Timezone set to Africa/Kampala

Verify:

timedatectl

1. Install Required Packages

sudo apt update
sudo apt install -y         git         python3         python3-venv         python3-pip         sqlite3         tree         acl

2. Create Service User

sudo useradd -r -s /usr/sbin/nologin -d /opt/isp-status ispstatus

Verify:

id ispstatus

3. Restore Application Code

Clone or restore the repository into:

/opt/isp-status

Example:

sudo mkdir -p /opt
sudo git clone <repo> /opt/isp-status
sudo chown -R root:root /opt/isp-status

If no remote Git host is trusted or configured, restore from a verified local Git bundle instead:

sha256sum -c /path/to/isp-status-YYYYMMDD-HHMMSSZ.bundle.sha256
git bundle verify /path/to/isp-status-YYYYMMDD-HHMMSSZ.bundle
sudo mkdir -p /opt
sudo git clone /path/to/isp-status-YYYYMMDD-HHMMSSZ.bundle /opt/isp-status
sudo chown -R root:root /opt/isp-status

See runbooks/local-git-checkpoints.md for the local-only checkpoint workflow.

4. Create Runtime Directories

sudo mkdir -p /var/log/isp-status
sudo mkdir -p /var/lib/isp-status
sudo mkdir -p /run/isp-status
sudo mkdir -p /opt/isp-status/backups

5. Apply Root Permission Model

sudo /opt/isp-status/tools/perm_reset_root.sh

This ensures:

  • /etc/isp-status → root:ispstatus (750/640 model)
  • Runtime dirs owned by ispstatus
  • Backups dir writable by ispstatus
  • NO recursive ACLs on system directories

6. Install systemd Units

sudo /opt/isp-status/systemd/install-units.sh

Verify:

systemctl status isp-status.service
systemctl list-timers --all | grep isp

7. Validate Snapshot System

sudo systemctl start isp-status-snapshot-full.service

Verify:

ls -lt /opt/isp-status/backups

8. Verify Permission Boundaries

Confirm no ACL contamination:

getfacl -R /etc 2>/dev/null | grep ispstatus

Confirm SSH integrity:

systemctl status ssh

9. Final Health Check

systemctl status isp-status.service
systemctl list-timers --all
journalctl -u isp-status.service -n 50

Rebuild Complete When

  • App responding
  • Timers active
  • Snapshot produced
  • No ACL contamination
  • SSH operational