ASE/docs/FTP_SFTP_SETUP.md

# FTP/SFTP Server Setup Guide

Il sistema ASE supporta sia FTP che SFTP utilizzando lo stesso codice Python. La modalità viene selezionata tramite la variabile d'ambiente `FTP_MODE`.

## Modalità Supportate

### FTP (File Transfer Protocol)
- **Protocollo**: FTP classico
- **Porta**: 21 (o configurabile)
- **Sicurezza**: Non criptato (considera FTPS per produzione)
- **Porte passive**: Richiede un range di porte configurabile
- **Caso d'uso**: Compatibilità con client legacy, performance

### SFTP (SSH File Transfer Protocol)
- **Protocollo**: SSH-based file transfer
- **Porta**: 22 (o configurabile)
- **Sicurezza**: Criptato tramite SSH
- **Porte passive**: Non necessarie (usa solo la porta SSH)
- **Caso d'uso**: Sicurezza, firewall-friendly

## Configurazione

### Variabili d'Ambiente

#### Comuni a entrambi i protocolli
```bash
FTP_MODE=ftp              # o "sftp"
DB_HOST=mysql-server
DB_PORT=3306
DB_USER=ase_user
DB_PASSWORD=password
DB_NAME=ase_lar
LOG_LEVEL=INFO
```

#### Specifiche per FTP
```bash
FTP_PASSIVE_PORTS=40000   # Prima porta del range passivo
FTP_EXTERNAL_IP=192.168.1.100  # VIP per HA
```

#### Specifiche per SFTP
```bash
# Nessuna variabile specifica - richiede solo SSH host key
```

## Setup Docker Compose

### Server FTP

```yaml
services:
  ftp-server:
    build: .
    container_name: ase-ftp-server
    ports:
      - "2121:2121"
      - "40000-40449:40000-40449"
    environment:
      FTP_MODE: "ftp"
      FTP_PASSIVE_PORTS: "40000"
      FTP_EXTERNAL_IP: "192.168.1.100"
      DB_HOST: "mysql-server"
      DB_USER: "ase_user"
      DB_PASSWORD: "password"
      DB_NAME: "ase_lar"
    volumes:
      - ./logs/ftp:/app/logs
      - ./data:/app/data
```

### Server SFTP

```yaml
services:
  sftp-server:
    build: .
    container_name: ase-sftp-server
    ports:
      - "2222:22"
    environment:
      FTP_MODE: "sftp"
      DB_HOST: "mysql-server"
      DB_USER: "ase_user"
      DB_PASSWORD: "password"
      DB_NAME: "ase_lar"
    volumes:
      - ./logs/sftp:/app/logs
      - ./data:/app/data
      - ./ssh_host_key:/app/ssh_host_key:ro
```

## Generazione SSH Host Key per SFTP

Prima di avviare il server SFTP, genera la chiave SSH:

```bash
ssh-keygen -t rsa -b 4096 -f ssh_host_key -N ""
```

Questo crea:
- `ssh_host_key` - Chiave privata (monta nel container)
- `ssh_host_key.pub` - Chiave pubblica

## Autenticazione

Entrambi i protocolli usano lo stesso sistema di autenticazione:

1. **Admin user**: Configurato in `ftp.ini`
2. **Virtual users**: Salvati nella tabella `virtusers` del database
3. **Password**: SHA256 hash
4. **Sincronizzazione**: Automatica tra tutte le istanze (legge sempre dal DB)

## Comandi SITE (solo FTP)

I comandi SITE sono disponibili solo in modalità FTP:

```bash
ftp> site addu username password  # Aggiungi utente
ftp> site disu username           # Disabilita utente
ftp> site enau username           # Abilita utente
ftp> site lstu                    # Lista utenti
```

In modalità SFTP, usa lo script `load_ftp_users.py` per gestire gli utenti.

## High Availability (HA)

### Setup HA con FTP
Puoi eseguire più istanze FTP che condividono lo stesso VIP:

```yaml
ftp-server-1:
  environment:
    FTP_EXTERNAL_IP: "192.168.1.100"  # VIP condiviso
  ports:
    - "2121:2121"
    - "40000-40449:40000-40449"

ftp-server-2:
  environment:
    FTP_EXTERNAL_IP: "192.168.1.100"  # Stesso VIP
  ports:
    - "2122:2121"
    - "41000-41449:40000-40449"  # Range diverso sull'host
```

### Setup HA con SFTP
Più semplice, nessuna configurazione di porte passive:

```yaml
sftp-server-1:
  ports:
    - "2222:22"

sftp-server-2:
  ports:
    - "2223:22"
```

## Testing

### Test FTP
```bash
ftp 192.168.1.100 2121
# Username: admin (o utente dal database)
# Password: <password>
ftp> ls
ftp> put file.csv
ftp> by
```

### Test SFTP
```bash
sftp -P 2222 admin@192.168.1.100
# Password: <password>
sftp> ls
sftp> put file.csv
sftp> exit
```

## Monitoring

I log sono disponibili sia su file che su console (Docker):

```bash
# Visualizza log FTP
docker logs ase-ftp-server

# Visualizza log SFTP
docker logs ase-sftp-server

# Segui i log in tempo reale
docker logs -f ase-ftp-server
```

## Troubleshooting

### FTP: Errore "Can't connect to passive port"
- Verifica che il range di porte passive sia mappato correttamente in Docker
- Controlla che `FTP_EXTERNAL_IP` sia impostato correttamente
- Verifica che `FTP_PASSIVE_PORTS` corrisponda al range configurato

### SFTP: Errore "Connection refused"
- Verifica che l'SSH host key esista e sia montato correttamente
- Controlla i permessi del file SSH host key (deve essere leggibile)
- Installa `asyncssh`: `pip install asyncssh`

### Autenticazione fallita (entrambi)
- Verifica che il database sia raggiungibile
- Controlla che le credenziali del database siano corrette
- Verifica che l'utente esista nella tabella `virtusers` e sia abilitato (`disabled_at IS NULL`)

## Dipendenze

### FTP
```bash
pip install pyftpdlib mysql-connector-python
```

### SFTP
```bash
pip install asyncssh aiomysql
```

## Performance

- **FTP**: Più veloce per trasferimenti di file grandi, minore overhead
- **SFTP**: Leggermente più lento a causa della crittografia SSH, ma più sicuro

## Sicurezza

### FTP
- ⚠️ Non criptato - considera FTPS per produzione
- Abilita `permit_foreign_addresses` per NAT/proxy
- Usa firewall per limitare accesso

### SFTP
- ✅ Completamente criptato tramite SSH
- ✅ Più sicuro per Internet pubblico
- ✅ Supporta autenticazione a chiave pubblica (future enhancement)

## Migration

Per migrare da FTP a SFTP:

1. Avvia server SFTP con stesse credenziali database
2. Testa connessione SFTP
3. Migra client gradualmente
4. Spegni server FTP quando tutti i client sono migrati

Gli utenti e i dati rimangono gli stessi!