Ti connetti a un server via FTP dal tuo editor di codice, inserisci host, login e password e in risposta compare una riga rossa: SSL/TLS required on the data channel. Ti suona familiare? Questo errore si verifica quando il server richiede una connessione cifrata, ma il client prova a collegarsi in FTP semplice. Succede spesso con i provider di hosting che usano certificati auto-firmati.

In passato il problema si risolveva su Atom con il plugin Remote FTP. Atom è morto a dicembre 2022, ma l'errore non è sparito. Sopravvive su VS Code, FileZilla, Pulsar e qualsiasi client FTP che si connetta a un server con certificato SSL auto-firmato.

In questo post vediamo tre metodi funzionanti per aggirare SSL/TLS required on the data channel: per Atom/Pulsar tramite .ftpconfig, per VS Code con l'estensione SFTP e per i client con interfaccia grafica come FileZilla. Più un avvertimento importante: quando rejectUnauthorized: false è una soluzione accettabile e quando invece è un buco di sicurezza.

💡 Panoramica rapida:

• Origine dell'errore: il server richiede TLS, il client invia FTP semplice, la connessione cade nella fase del canale dati.
• .ftpconfig con rejectUnauthorized: false e secure: true è la soluzione per Atom e il suo fork Pulsar che funziona con il plugin Remote FTP.
• Su VS Code, l'estensione SFTP di liximomo con il parametro secure: true risolve lo stesso problema a livello di configurazione di sftp.json.
• Su FileZilla e altri client con interfaccia grafica basta cambiare il protocollo da FTP a FTPS (TLS esplicito) e accettare il certificato manualmente.
• Sicurezza: rejectUnauthorized: false disabilita la verifica del certificato ed è accettabile solo per server di sviluppo e ambienti di test, mai in produzione.

Da dove nasce l'errore SSL/TLS required on the data channel

Il protocollo FTP funziona su due canali: canale di controllo (comandi) e canale dati (trasferimento effettivo dei file). Quando il server è configurato per FTPS (FTP over TLS), li cifra entrambi. Un client che prova a connettersi in FTP semplice supera l'autenticazione sul canale di controllo, ma quando tenta di aprire il canale dati il server risponde: 550 SSL/TLS required on the data channel.

La ragione tecnica sta nell'implementazione TLS lato Node.js (su cui sono costruiti sia Remote FTP per Atom sia l'estensione SFTP per VS Code). Node.js convalida i certificati SSL in modo predefinito. Un certificato auto-firmato non supera questa convalida e la connessione cade. La soluzione: dire esplicitamente al client di non verificare il certificato (rejectUnauthorized: false) oppure passare a FTPS esplicito con accettazione manuale del certificato.

Soluzione 1: .ftpconfig corretto per Atom e Pulsar

Atom è stato dismesso ufficialmente a dicembre 2022, ma il suo fork Pulsar (ex Atom) è pienamente compatibile con i pacchetti Atom, incluso Remote FTP. La soluzione consiste nello specificare i secureOptions corretti in .ftpconfig.

Crea (o modifica) il file .ftpconfig nella root del progetto:

1
{
2
    "protocol": "ftp",
3
    "host": "your.server.com",
4
    "port": 21,
5
    "user": "login",
6
    "pass": "password",
7
    "promptForPass": false,
8
    "remote": "/",
9
    "secure": true,
10
    "secureOptions": {
11
        "rejectUnauthorized": false
12
    },
13
    "connTimeout": 10000,
14
    "keepalive": 10000
15
}

Parametri chiave:

• secure: true abilita TLS sia per il canale di controllo sia per quello dati;
• rejectUnauthorized: false disabilita la verifica del certificato (Node.js smette di pretendere un certificato valido dal server);
• port: 21 è la porta standard per FTP; per FTPS via TLS implicito si usano la porta 990 e protocol: "ftps".

Dopo aver salvato .ftpconfig, riconnettiti al server e l'errore SSL/TLS required on the data channel sparirà.

Soluzione 2: configurare l'estensione SFTP su VS Code

L'estensione più diffusa per FTP/SFTP su VS Code è SFTP di liximomo (oltre 1,3 milioni di installazioni). L'errore 550 SSL/TLS required on the control channel è discusso nella issue #872.

Dopo aver installato l'estensione, esegui Ctrl+Shift+P → SFTP: Config e si aprirà il file sftp.json. Configuralo come segue:

1
{
2
    "name": "My server",
3
    "host": "your.server.com",
4
    "protocol": "ftp",
5
    "port": 21,
6
    "secure": true,
7
    "username": "login",
8
    "password": "password",
9
    "remotePath": "/",
10
    "uploadOnSave": true
11
}

Il parametro secure: true è l'equivalente diretto di rejectUnauthorized: false di .ftpconfig. Dice all'estensione di usare FTPS e di non interrompere la connessione quando incontra un certificato auto-firmato.

Se il server usa FTPS implicito (porta 990), cambia protocol in ftps e port in 990. Salva sftp.json, esegui SFTP: Download Project e l'estensione si connetterà scaricando il contenuto di remotePath.

Soluzione 3: FileZilla e altri client con interfaccia grafica

Nei client con interfaccia grafica il problema si risolve in modo ancora più semplice a livello di interfaccia. Su FileZilla:

• Apri il Gestore siti (Ctrl+S).
• Seleziona la connessione e nel campo Protocollo passa da FTP a FTP over TLS (explicit).
• Alla prima connessione FileZilla mostrerà una finestra con l'impronta del certificato; clicca Fidati di questo certificato e spunta "Fidati sempre".

Lo stesso principio vale per WinSCP, Cyberduck e qualsiasi client FTP moderno: specifica esplicitamente il protocollo FTPS e accetta il certificato manualmente. Niente file di configurazione, solo interfaccia.

Quando NON devi disabilitare la verifica del certificato

rejectUnauthorized: false è un indebolimento deliberato della sicurezza. Stai dicendo al client: «accetta QUALSIASI certificato, anche uno contraffatto». Questo è accettabile in tre casi:

• Un server di sviluppo locale o un ambiente di staging non accessibile da internet.
• Un tuo VPS, dove sai esattamente da dove proviene il certificato.
• Un ambiente di test dietro una VPN aziendale.

Su un server di produzione con certificato auto-firmato è meglio spendere 15 minuti per configurare Let's Encrypt, un certificato SSL gratuito che tutti i client riconoscono senza bisogno di rejectUnauthorized: false.

Guarda questo breve tutorial sulla connessione SFTP in VS Code, che copre tutti i passaggi dall'installazione dell'estensione alla prima connessione al server:

⁉️🤔 Domande frequenti

L'errore persiste dopo aver impostato secure: true; cos'altro devo controllare?

Per prima cosa verifica la porta. FTPS esplicito funziona sulla porta 21, quello implicito sulla 990. Se l'amministratore del server richiede FTPS implicito ma tu hai indicato protocol: "ftp" con port: 21, la connessione non si stabilirà per quanti cambi tu possa fare a secureOptions. Controlla il pannello di hosting o chiedi all'amministratore quale modalità FTPS usa il server.

Posso usare SFTP invece di FTPS?

Sì, ed è l'opzione preferibile. SFTP (SSH File Transfer Protocol) funziona su SSH, non su FTP, quindi i problemi di certificato SSL semplicemente non esistono. Se il server fornisce accesso SSH, usa SFTP invece di FTPS. Nello stesso .ftpconfig ti basta cambiare protocol in sftp e port in 22.

Atom è stato dismesso; Remote FTP funziona ancora?

Il pacchetto Remote FTP è disponibile nel repository di Atom, ma l'editor non riceve aggiornamenti da dicembre 2022 e contiene vulnerabilità note. GitHub ha persino revocato i certificati di firma del codice per Atom a gennaio 2023. Se Atom si avvia ancora sulla tua macchina, migra al fork Pulsar, che importa gli stessi pacchetti e configurazioni senza modifiche.

Cosa mi dici di VS Code Remote SSH?

Remote SSH è un'ottima alternativa alle connessioni FTP se il server gira su Linux e ha accesso SSH. Lavori direttamente sui file, senza sincronizzazioni e problemi di certificati. Ma per gli hosting condivisi dove SSH è chiuso e l'accesso è solo via FTP, le soluzioni di questo post restano valide.

L'errore SSL/TLS required on the control channel (non canale dati): è la stessa cosa?

Sì, l'unica differenza è su quale canale è caduta la connessione. Il canale di controllo gestisce i comandi (autenticazione, navigazione), il canale dati gestisce il trasferimento dei file. Il server può richiedere TLS su uno qualsiasi dei due. La soluzione è identica: secure: true + rejectUnauthorized: false nella configurazione.

L'errore persiste: checklist finale

Scorri i punti; uno di questi risolverà il problema:

• Protocollo: secure: true è impostato nella configurazione (.ftpconfig o sftp.json)?
• Porta: FTPS esplicito = 21, implicito = 990, SFTP = 22. Verifica con le impostazioni del server.
• rejectUnauthorized: un certificato auto-firmato NON supera la convalida Node.js senza questa opzione.
• Client con interfaccia grafica: hai cambiato il Gestore siti in FTP over TLS (explicit) e accettato manualmente il certificato?
• SFTP invece di FTPS: se hai accesso SSH, dimentica FTP e passa a SFTP.

Se hai provato tutto e l'errore persiste, molto probabilmente il server è configurato per FTPS implicito (porta 990) mentre il client si connette alla porta 21. Verifica con il tuo provider di hosting la modalità e la porta richieste.

Questo errore non è un bug dell'editor ma una caratteristica dell'handshake TLS con certificato auto-firmato. Dopo una corretta configurazione sparisce su qualsiasi client: che sia Atom del 2018, Pulsar del 2026 o VS Code.