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

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

FTP_PASSIVE_PORTS=40000   # Prima porta del range passivo
FTP_EXTERNAL_IP=192.168.1.100  # VIP per HA

Specifiche per SFTP

# Nessuna variabile specifica - richiede solo SSH host key

Setup Docker Compose

Server FTP

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

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:

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:

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:

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:

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

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

Testing

Test FTP

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

Test SFTP

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):

# 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

pip install pyftpdlib mysql-connector-python

SFTP

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!