aggiunto server sftp con variabile d'ambiente FTP_MODE
This commit is contained in:
252
docs/FTP_SFTP_SETUP.md
Normal file
252
docs/FTP_SFTP_SETUP.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user