# Spiegazione — Modelli di configurazione del server (piano 261113, fase 1)
*Generato il 13-11-2026 · Ambito: conversazione (piano 261113, fase 1, modifiche non committate)*

## In breve
La VPS OVH è acquistata, ma nel repository non c'era nulla che dicesse ad Apache e a PHP come servire DOMUSCAN.

La fase 1 aggiunge in `configurazione/server/` quattro **modelli** (virtual host Apache, sicurezza globale di Apache, pool PHP‑FPM, cron del backup) e un `LEGGIMI.md` che spiega dove copiarli. Un test bash controlla che i modelli rispettino le regole di sicurezza decise nel piano.

Nessun file PHP dell'applicazione è stato toccato. Sul server non è ancora stato installato niente: quello è il lavoro della fase 4.

## Il contesto

**Apache + PHP‑FPM.** In locale l'app gira con `php -S localhost:8000 -t pubblico`, il server integrato di PHP, adatto solo allo sviluppo. Sul server si usano due processi separati:
- **Apache** riceve le richieste HTTP/HTTPS e serve direttamente i file statici (CSS, JS);
- per i `.php` Apache passa la richiesta a **PHP‑FPM** (FastCGI Process Manager) attraverso un *socket Unix*, cioè un file speciale come `/run/php-fpm/domuscan-staging.sock`. È la variante moderna di `mod_php`: PHP gira con un utente diverso da quello di Apache, e ogni ambiente può avere il proprio *pool* di processi con impostazioni proprie.

**Perché "modelli" e non file pronti.** Sulla stessa VPS potranno convivere `staging` e `produzione`. Per questo ogni file usa il segnaposto `__AMBIENTE__`, che si sostituisce al momento della copia:

```bash
sed "s/__AMBIENTE__/staging/g" apache_domuscan.conf > /etc/httpd/conf.d/10_domuscan_staging.conf
```

**AlmaLinux invece di Debian.** Il piano proponeva Debian 13. Nella colonna "utente" delle decisioni hai indicato AlmaLinux, e i modelli seguono quella scelta. Le differenze pratiche:

| | Debian | AlmaLinux (usato) |
|---|---|---|
| Configurazione Apache | `/etc/apache2/sites-available/` + `a2ensite` | `/etc/httpd/conf.d/*.conf`, caricati in ordine alfabetico |
| Utente di Apache | `www-data` | `apache` |
| Pool PHP‑FPM | `/etc/php/8.4/fpm/pool.d/` | `/etc/php-fpm.d/` |
| Certificati | `/etc/ssl/` | `/etc/pki/tls/` |
| Controllo degli accessi | AppArmor (permissivo per Apache) | **SELinux attivo**: senza regole Apache non legge `/srv` |

**Un vincolo che viene dal codice.** Fuori da `sviluppo` l'app imposta il cookie di sessione come `Secure` (`sorgenti/comune/sessione.php:36`). Un cookie `Secure` il browser lo rimanda solo su HTTPS: in HTTP semplice il login sembrerebbe funzionare ma la sessione andrebbe persa a ogni pagina. Per questo il virtual host porta tutto su HTTPS, con un certificato autofirmato finché non arriva il dominio.

## Cosa è stato guardato

| File | Perché è stato letto | Cosa ne abbiamo ricavato |
|---|---|---|
| `documentazione/ambienti.md` | Procedura prevista per staging e produzione | Struttura `/srv/domuscan/<ambiente>/`, `.env` con permessi `600`, privilegio `TRIGGER` per MariaDB |
| `documentazione/backup.md` | Il cron del backup doveva rispettarla | Backup notturno, RPO 24 h: da qui l'orario delle 03:15 |
| `sorgenti/comune/sessione.php` | Capire come si comporta la sessione in staging | Cookie `Secure` fuori da `sviluppo`, quindi HTTPS obbligatorio |
| `sorgenti/comune/viste.php` (righe 138–145) | Sapere quali header invia già PHP | CSP, `X-Frame-Options`, `nosniff`, `Cache-Control: no-store` e HSTS sono già inviati: Apache deve aggiungere solo quelli dei file statici, altrimenti si duplicano |
| `sorgenti/comune/audit.php:53` | Capire se serve `mod_remoteip` | L'IP viene da `REMOTE_ADDR`; senza proxy davanti è corretto, quindi niente modulo |
| `sorgenti/comune/avvio.php:107` e una ricerca di `getenv`/`save_path` | Verificare che le restrizioni del pool non rompano l'app | L'unico `getenv` è facoltativo (ha un valore predefinito) e l'app non imposta `session.save_path`: `clear_env = yes` e le sessioni private sono sicuri |
| `strumenti/migra.php` | Controllare se uno strumento è raggiungibile dal web | Rifiuta già le richieste non CLI, e comunque è fuori da `pubblico/` |
| `test/libreria_test.sh`, `test/test_configurazione_ambienti.sh` | Scrivere il nuovo test nello stesso stile | Funzioni `verificaCondizione` e `concludiTest`, intestazione, stile dei messaggi |
| Piano 261113, decisioni 1–7 | Applicare le scelte che hai scritto nella colonna "utente" | AlmaLinux, certificato autofirmato, nessuna copia remota, caricamento a mano |

## Cosa è stato modificato

### 1. Virtual host Apache — `configurazione/server/apache_domuscan.conf` (nuovo)

**Prima:** il file non esisteva.

**Dopo** (parti principali):
```apache
<VirtualHost *:80>
    RewriteEngine On
    RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]
    ...
</VirtualHost>

<VirtualHost *:443>
    DocumentRoot /srv/domuscan/__AMBIENTE__/app/pubblico
    ...
    <Directory />
        Options None
        AllowOverride None
        Require all denied
    </Directory>

    <Directory /srv/domuscan/__AMBIENTE__/app/pubblico>
        Options -Indexes -FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    <FilesMatch "^\.">
        Require all denied
    </FilesMatch>
    <FilesMatch "(\.map|^composer\.(json|lock))$">
        Require all denied
    </FilesMatch>

    <FilesMatch "\.php$">
        SetHandler "proxy:unix:/run/php-fpm/domuscan-__AMBIENTE__.sock|fcgi://domuscan-__AMBIENTE__"
    </FilesMatch>

    <Directory /srv/domuscan/__AMBIENTE__/app/pubblico/risorse>
        Header set Cache-Control "public, max-age=604800"
    </Directory>
    ...
</VirtualHost>
```

**Come:**
- **Redirect con `mod_rewrite`.** Non conosciamo ancora il nome del sito: oggi è un IP, domani un dominio. `%{HTTP_HOST}` riprende ciò che il browser ha chiesto, quindi la stessa regola funziona in entrambi i casi. Un `Redirect permanent / https://...` avrebbe richiesto di scrivere l'indirizzo a mano.
- **Prima tutto negato, poi solo `pubblico/` permesso.** Il blocco `<Directory />` chiude l'intero filesystem; quello successivo apre solo la document root. È il principio del "default deny": se un domani qualcuno aggiunge un `Alias` per errore, non espone niente.
- **`-Indexes`.** Senza `index.php` in una cartella, Apache non ne mostra l'elenco dei file.
- **`AllowOverride None`.** Apache ignora eventuali `.htaccess`: tutta la configurazione sta in un posto solo, e Apache non deve cercare un file `.htaccess` in ogni cartella a ogni richiesta.
- **`<FilesMatch "^\.">`.** Blocca `.env`, `.git` e simili, anche se un giorno finissero per sbaglio dentro `pubblico/`. Il secondo blocco nasconde i `.map` di Bootstrap e i file di Composer.
- **`SetHandler "proxy:unix:...|fcgi://domuscan-__AMBIENTE__"`.** Manda i `.php` al socket del pool. La parte dopo `|` è solo un *nome* del collegamento: deve essere diverso per ogni ambiente. Con lo stesso nome (`fcgi://localhost`, quello dei tutorial) due pool sulla stessa VPS rischierebbero di condividere le connessioni.
- **Cache di 7 giorni solo su `risorse/`.** I file statici si possono tenere in cache; le pagine PHP mandano già `no-store` da `viste.php`.

**Perché:** piano 261113, fase 1, prima riga della tabella; percorsi adattati ad AlmaLinux (decisione 1).

**Da sapere:** in `LEGGIMI.md` il file va copiato come `10_domuscan_<ambiente>.conf`. Apache su AlmaLinux legge `conf.d/` in ordine alfabetico, e anche `ssl.conf` definisce un virtual host sulla porta 443. Quando si chiama il server per IP vince il **primo** virtual host caricato, e `10_…` viene prima di `ssl.conf` perché le cifre precedono le lettere.

### 2. Sicurezza globale di Apache — `configurazione/server/apache_sicurezza.conf` (nuovo)

**Dopo:**
```apache
ServerTokens Prod
ServerSignature Off
TraceEnable Off

SSLProtocol -all +TLSv1.2 +TLSv1.3
SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:...:ECDHE-RSA-CHACHA20-POLY1305
SSLHonorCipherOrder off
SSLSessionTickets off

<FilesMatch "\.(css|js|png|jpe?g|gif|svg|ico|woff2?)$">
    Header set X-Content-Type-Options "nosniff"
</FilesMatch>
```

**Come:**
- `ServerTokens Prod` riduce l'header a `Server: Apache`, senza versione né sistema operativo. `ServerSignature Off` toglie la firma dalle pagine di errore. A chi attacca non si regala la versione da cercare nei bollettini di vulnerabilità.
- `TraceEnable Off` disattiva il metodo HTTP `TRACE`, che rimanda indietro la richiesta così com'è ed è usato in vecchi attacchi per leggere i cookie.
- **TLS:** `-all` toglie tutto, poi si aggiungono solo 1.2 e 1.3. Tutti i cifrari scelti sono ECDHE (*forward secrecy*: chi ruba domani la chiave del certificato non decifra il traffico registrato oggi) e AEAD (GCM o ChaCha20).
- **`nosniff` solo sui file statici.** PHP lo invia già per le pagine. Se Apache lo aggiungesse a tutto, sulle pagine PHP l'header comparirebbe due volte.

**Perché:** piano 261113, fase 1, seconda riga della tabella.

### 3. Pool PHP‑FPM — `configurazione/server/php_fpm_domuscan.conf` (nuovo)

**Dopo** (estratto):
```ini
[domuscan-__AMBIENTE__]
user  = domuscan-__AMBIENTE__
listen       = /run/php-fpm/domuscan-__AMBIENTE__.sock
listen.owner = apache
listen.mode  = 0660

pm                      = ondemand
pm.max_children         = 10
pm.process_idle_timeout = 10s

clear_env = yes

php_admin_flag[display_errors]  = off
php_admin_value[session.save_path] = /srv/domuscan/__AMBIENTE__/dati/sessioni
php_admin_value[open_basedir] = /srv/domuscan/__AMBIENTE__/app/:/srv/domuscan/__AMBIENTE__/dati/:/tmp/
php_admin_value[upload_max_filesize] = 20M
```

**Come:**
- **Due utenti diversi.** PHP gira come `domuscan-<ambiente>`, proprietario del codice e del `.env`. Apache (`apache`) può solo scrivere nel socket (`listen.owner = apache`, `0660`). Così Apache non può leggere `.env`, che ha permessi `600`.
- **`pm = ondemand`.** I processi PHP nascono quando arrivano richieste e muoiono dopo 10 s di inattività. Su un ambiente di test con poco traffico non si tiene memoria occupata per niente. In produzione, con traffico costante, si valuterà `dynamic`.
- **`php_admin_*` e `php_value`.** Le impostazioni `php_admin_*` **non** si possono cambiare dal codice con `ini_set()`. `display_errors = off` è quindi garantito anche se un errore nel codice provasse a riattivarlo. Il codice lo imposta già (`avvio.php`, ultima riga), ma questa è una seconda protezione.
- **`open_basedir`.** PHP può aprire solo file sotto `app/`, `dati/` e `/tmp/`. Una vulnerabilità di tipo "leggi un file a scelta" non arriverebbe a `/etc/passwd` né ai file dell'altro ambiente.
- **`clear_env = yes`.** Le variabili d'ambiente di sistema non arrivano a PHP. L'unica che il codice legge (`DOMUSCAN_FILE_CONFIGURAZIONE`, in `avvio.php:107`) ha un valore predefinito (`?:`), quindi l'app ripiega correttamente sul `.env`.
- **Sessioni private.** Per default PHP salva le sessioni in una cartella condivisa. Una cartella per ambiente impedisce che staging e produzione si vedano le sessioni a vicenda.

**Perché:** piano 261113, fase 1, terza riga della tabella.

**Da sapere:** le cartelle `dati/log` e `dati/sessioni` devono **esistere** prima di avviare il pool, altrimenti PHP non riesce a scrivere log e sessioni. `LEGGIMI.md` le elenca.

### 4. Cron del backup — `configurazione/server/cron_domuscan` (nuovo)

**Dopo:**
```cron
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

15 3 * * * domuscan-__AMBIENTE__ bash /srv/domuscan/__AMBIENTE__/app/strumenti/backup.sh --env /srv/domuscan/__AMBIENTE__/app/.env >> /srv/domuscan/__AMBIENTE__/dati/log/backup_cron.log 2>&1
```

**Come:** i file in `/etc/cron.d/` hanno un campo in più rispetto al `crontab` personale: l'**utente** (qui `domuscan-<ambiente>`) tra l'orario e il comando. `PATH` va scritto esplicitamente perché cron parte con un PATH minimo. Lo script si lancia con `bash …` invece che direttamente: hai scelto di caricare i file a mano (decisione 7), e il permesso di esecuzione può perdersi nel trasferimento.

**Perché:** piano 261113, fase 1, quarta riga. L'orario è in UTC (le 04:15 in Italia d'inverno), fuori dall'orario di lavoro degli studi.

**Da sapere:** `strumenti/backup.sh` non esiste ancora: arriva con la fase 2. Se installi il cron prima, troverai un errore "No such file" in `backup_cron.log` ogni notte.

### 5. Istruzioni di installazione — `configurazione/server/LEGGIMI.md` (nuovo)

Spiega dove va ogni modello sul server, come sostituire `__AMBIENTE__`, quali cartelle creare, come generare il certificato autofirmato sull'IP (`subjectAltName=IP:…`: i browser moderni ignorano il CN e guardano solo il SAN), il firewall (`firewall-cmd`) e soprattutto **SELinux**:

```bash
semanage fcontext -a -t httpd_sys_content_t    "/srv/domuscan/<ambiente>/app(/.*)?"
semanage fcontext -a -t httpd_sys_rw_content_t "/srv/domuscan/<ambiente>/dati(/.*)?"
restorecon -Rv /srv/domuscan/<ambiente>
setsebool -P httpd_can_network_connect_db on
```

**Come:** con SELinux ogni file ha un'*etichetta*, e i processi web possono toccare solo file con le etichette previste. `/srv` non ce le ha: senza queste regole Apache risponde 403 anche con permessi Unix corretti, ed è un errore che fa perdere ore. Con `semanage fcontext` la regola diventa permanente; `restorecon` la applica ai file esistenti. `httpd_can_network_connect_db` permette a PHP di aprire la connessione TCP verso MariaDB (`DB_HOST=127.0.0.1`).

**Perché:** la tabella della fase 1 prevedeva un `LEGGIMI.md` con destinazioni e segnaposto. La parte su SELinux è stata aggiunta perché AlmaLinux (decisione 1) la rende indispensabile.

### 6. Test automatico — `test/test_configurazione_server.sh` (nuovo)

**Dopo** (esempi):
```bash
document_root=$(grep -E '^\s*DocumentRoot ' "$FILE_APACHE" | awk '{print $2}')
[[ "$document_root" == */app/pubblico ]]
verificaCondizione "DocumentRoot punta a pubblico/ ($document_root)" $?

socket_apache=$(grep -oE 'proxy:unix:[^|]+' "$FILE_APACHE" | sed 's/^proxy:unix://')
socket_pool=$(grep -E '^\s*listen\s*=' "$FILE_POOL" | sed -E 's/^\s*listen\s*=\s*//')
[ -n "$socket_apache" ] && [ "$socket_apache" = "$socket_pool" ]
verificaCondizione "Apache usa il socket del pool PHP-FPM ($socket_apache)" $?
```

**Come:** 32 asserzioni con `grep` sui modelli:
- presenza e intestazione dei file;
- `DocumentRoot`, `AllowOverride None`, `-Indexes`, blocco dei file nascosti;
- redirect a HTTPS e versione di TLS;
- `display_errors` ed `expose_php` disattivati;
- orario del cron;
- presenza del segnaposto;
- assenza di segreti (`PRIVATE KEY`, `password=…`).

Il controllo più utile è quello sul **socket**: se un giorno qualcuno rinomina il socket nel pool e non nel virtual host, Apache risponderebbe "503 Service Unavailable" su tutte le pagine PHP. Il test lo scopre prima di andare sul server.

**Perché:** piano 261113, fase 1, paragrafo "Test automatico".

**Da sapere:** il test controlla le **regole**, non la **sintassi**. Una direttiva Apache scritta male passa il test. Per questo il TODO ha ora un test manuale con `apachectl configtest` e `php-fpm -t` da eseguire sulla VPS.

### 7. File di gestione — `TODO.md`, piano, `next_commit.md`

- `TODO.md`: quattro nuove voci nei MANUAL TESTS (sintassi sul server, accessi bloccati, header, SELinux). Le due voci `[plan 261113]` restano tali, perché mancano ancora le fasi 2–4.
- Piano: la fase 1 è `fatta (13/11/2026)` e lo stato del piano è `IN CORSO`.
- `next_commit.md`: riscritto con il messaggio per il prossimo commit. Il contenuto precedente era il messaggio del commit `6942eae`, già fatto.

### Esito dei test

| Suite | Esito |
|---|---|
| `test_configurazione_server.sh` (nuovo) | superato, 32/32 |
| `test_configurazione_ambienti.sh`, `test_php.sh` (37 test, con MariaDB avviato), `test_verifica_ambiente.sh` | superati |
| `test_repository.sh` | **fallito**, ma già prima di questo lavoro: `PROJECT DOCS/` non è più escluso dal `.gitignore` (commit `6942eae`). Non è stato toccato |

## Come ripristinare
- **Tutto insieme:** i file nuovi non sono ancora in git, quindi si cancellano:
  ```bash
  rm -r configurazione/server test/test_configurazione_server.sh
  git restore TODO.md
  ```
  `git restore TODO.md` annulla anche il `[plan 261113]` messo da `/run-next`; se vuoi tenerlo, togli a mano solo le quattro righe `[manual]` che iniziano con "Verificare che i modelli…", "Verificare che la VPS…", "Verificare gli header…" e "Verificare che SELinux…". `next_commit.md` e il piano sono ignorati da git: vanno sistemati a mano (stato della fase 1 di nuovo `pronta`, stato del piano `IN ATTESA DI APPROVAZIONE`).
- **Dopo il commit:** `git revert <hash>`.
- **Una modifica sola:** cancellare il singolo modello in `configurazione/server/`.
- **Attenzione:**
  - Apache e il pool sono legati dal **nome del socket**: se ne togli o cambi uno, cambia anche l'altro, o tutte le pagine PHP danno 503.
  - Togliendo un modello, `test_configurazione_server.sh` fallisce: va aggiornato insieme.
  - Il cron richiama `strumenti/backup.sh` (fase 2): se la fase 2 cambia nome o opzioni dello script, va aggiornato anche il cron.

## Cosa portarsi a casa
- **Prima chiudere tutto, poi aprire il minimo.** `<Directory />` con `Require all denied` e una sola cartella permessa protegge anche da errori di configurazione futuri.
- **Non duplicare gli header tra Apache e PHP.** Prima di aggiungere un header nel web server, controlla se l'applicazione lo invia già (qui `viste.php`).
- **`php_admin_*` è una cintura di sicurezza.** Le impostazioni critiche (`display_errors`, `open_basedir`) messe nel pool non sono modificabili dal codice.
- **Su AlmaLinux/RHEL il primo sospettato di un 403 "inspiegabile" è SELinux.** Si controlla con `ausearch -m avc -ts recent`.
- **I test sui file di configurazione verificano le regole, non la sintassi.** La sintassi si verifica solo con lo strumento del server (`apachectl configtest`).
