# SquidGuard-Listen per GitLab self-managed (Shell-Runner)

## Idee / Sicherheitsmodell

- **Ein Repo pro Arbeitsgruppe** (`squidguard/ag01` .. `squidguard/ag08`).
  GitLab-Rechte am Projekt = wer die beiden Dateien `AG<NN>domain` /
  `AG<NN>url` aendern darf. Nur AG01-Mitglieder haben Developer im Repo
  `ag01`. Das ist die eigentliche Zugriffskontrolle.
- **Ein zentrales Deploy-Repo** (`squidguard/deploy`), nur Ops beschreibbar.
  Hier liegen Deploy-Skript und Secrets. Die AG-Repos enthalten KEINE
  Secrets -> auch wenn eine AG ihre `.gitlab-ci.yml` frei bearbeitet, kann
  sie damit nur die zentrale Pipeline anstossen, nichts ausspaehen.
- **Dedizierter Shell-Runner** nur fuer das Deploy-Repo (nicht mit den
  AG-Repos teilen!), Tag `squidguard-shell`.

## Dateibaum

    deploy-repo/            -> Inhalt des Repos squidguard/deploy
      .gitlab-ci.yml
      scripts/validate.sh
      scripts/deploy.sh
      config/proxies.env
    ag-repo/                -> Vorlage fuer jedes Repo squidguard/agNN
      .gitlab-ci.yml        (optional, nur fuer Sofort-Deploy)
      AG01domain
      AG01url
    proxy/                  -> auf BEIDE Squid-Proxies installieren
      usr-local-sbin-squidguard-rebuild.sh
      usr-local-sbin-squidguard-reload.sh
      sudoers.d-squidguard-deploy
      squidGuard.conf.snippet

## Einrichtung Proxys (proxy1 + proxy2, je identisch)

    # Deploy-User anlegen
    useradd -m -s /bin/bash deploy
    install -d -o deploy -g deploy /var/lib/squidguard/incoming
    install -d -o proxy  -g proxy  /var/lib/squidguard/db
    install -d -o proxy  -g proxy  /var/lib/squidguard/backup   # fuer Auto-Rollback

    # Wrapper-Skripte installieren
    install -o root -g root -m 0755 usr-local-sbin-squidguard-rebuild.sh /usr/local/sbin/squidguard-rebuild.sh
    install -o root -g root -m 0755 usr-local-sbin-squidguard-reload.sh  /usr/local/sbin/squidguard-reload.sh

    # sudoers (WICHTIG: 0440, vorher pruefen)
    install -o root -g root -m 0440 sudoers.d-squidguard-deploy /etc/sudoers.d/squidguard-deploy
    visudo -c

    # SSH-Key des Runner-Users in ~deploy/.ssh/authorized_keys eintragen
    # squidGuard.conf.snippet in /etc/squidguard/squidGuard.conf einbauen

Hinweis: `PROXY_USER` in `squidguard-rebuild.sh` ist unter Debian/Ubuntu
`proxy`, unter RHEL/CentOS `squid` -> ggf. anpassen.

## Einrichtung Shell-Runner (auf dem Runner-Host)

    # Runner registrieren, an Projekt squidguard/deploy gebunden
    gitlab-runner register \
      --url https://gitlab.intern/ \
      --token <PROJECT_RUNNER_TOKEN_des_deploy_repos> \
      --executor shell \
      --tag-list squidguard-shell

    # Als Runner-User (meist gitlab-runner): SSH-Key + known_hosts anlegen
    sudo -u gitlab-runner ssh-keygen -t ed25519 -N '' -f ~gitlab-runner/.ssh/id_ed25519
    sudo -u gitlab-runner ssh-keyscan proxy1.intern proxy2.intern >> ~gitlab-runner/.ssh/known_hosts
    # der oeffentliche Key gehoert in ~deploy/.ssh/authorized_keys beider Proxys

## Einrichtung GitLab

1. Gruppe `squidguard` anlegen, darin Projekte `ag01`..`ag08` und `deploy`.
2. Je AG-Repo: nur die AG-Mitglieder als **Developer** hinzufuegen.
   Optional `main` als Protected Branch (Maintainer merged).
3. Group-Deploy-Token mit Scope `read_repository` erstellen ->
   im Deploy-Repo als CI/CD-Variablen `GIT_USER` / `GIT_TOKEN` hinterlegen
   (protected + masked).
4. Deploy-Repo: Pipeline-Zeitplan (Schedule) z.B. alle 5 Minuten anlegen.
5. Optional Sofort-Deploy: im Deploy-Repo ein Trigger-Token erzeugen und in
   jedem AG-Repo als `DEPLOY_TRIGGER_TOKEN` + `DEPLOY_PROJECT_ID`
   hinterlegen, dann `ag-repo/.gitlab-ci.yml` verwenden.

## Ablauf

Push in `ag01/main` -> (optional Trigger) -> zentrale Pipeline auf dem
Shell-Runner -> `deploy.sh`: klont alle AG-Repos, validiert, rsynct auf
beide Proxys, `squidguard-rebuild.sh AG<NN>` (DB je Gruppe neu),
am Ende `squidguard-reload.sh` (squid -k reconfigure).

Eine ungueltige Zeile wird schon in der CI-Validierung abgefangen und
gelangt gar nicht erst auf die Proxys.

## Auto-Rollback auf dem Proxy

`squidguard-rebuild.sh` sichert vor jeder Uebernahme den letzten
funktionierenden Stand einer Gruppe (Quelllisten + `.db`) nach
`/var/lib/squidguard/backup/AG<NN>/`. Schlaegt der Rebuild fehl -
erkannt an Exit-Code, Fehlermeldungen in der Ausgabe oder einer leeren
`.db` -, wird dieser Stand automatisch zurueckgespielt. Die Gruppe
laeuft damit unveraendert weiter, statt offline zu gehen.

`deploy.sh` behandelt das pro Gruppe isoliert: eine fehlgeschlagene
Gruppe wird uebersprungen (und zurueckgerollt), alle anderen Gruppen
gehen normal live, und Squid wird trotzdem neu geladen. Am Ende endet
die Pipeline mit Exit-Code 1 und listet die betroffenen `proxy/AG`
auf, damit der Fehler sichtbar bleibt.

Da die CI-Validierung Formatfehler bereits vorher abfaengt, ist der
Rollback vor allem die zweite Sicherung gegen Proxy-seitige Probleme
(z.B. squidGuard-Version, Rechte, kaputte Bestands-.db).