Łączy się Pan/Pani z serwerem przez FTP za pomocą edytora kodu, wprowadza host, login i hasło, a w odpowiedzi otrzymuje czerwony wiersz: SSL/TLS required on the data channel. Znajoma sytuacja? Ten błąd pojawia się, gdy serwer wymaga szyfrowanego połączenia, a klient próbuje połączyć się przez zwykły FTP. Szczególnie często na hostingach z certyfikatem z podpisem własnym.

Wcześniej problem ten rozwiązywano w Atomie przez wtyczkę Remote FTP. Atom umarł w grudniu 2022, ale błąd nigdzie nie zniknął. Występuje w VS Code, FileZilla, Pulsarze i każdym kliencie FTP, który łączy się z serwerem z samopodpisanym certyfikatem SSL.

W tym poście trzy działające sposoby na obejście SSL/TLS required on the data channel: dla Atom/Pulsar przez .ftpconfig, dla VS Code przez rozszerzenie SFTP oraz dla klientów GUI takich jak FileZilla. Plus ważne ostrzeżenie: kiedy rejectUnauthorized: false jest akceptowalnym obejściem, a kiedy dziurą w zabezpieczeniach.

💡 Szybki przegląd:

• Skąd bierze się błąd: serwer wymaga TLS, klient wysyła otwarty FTP, połączenie jest zrywane na etapie kanału danych.
• .ftpconfig z rejectUnauthorized: false oraz secure: true, rozwiązanie dla Atoma i forka Pulsar, które działa z wtyczką Remote FTP.
• W VS Code rozszerzenie SFTP od liximomo z parametrem secure: true rozwiązuje ten sam problem na poziomie konfiguracji sftp.json.
• W FileZilla i innych klientach GUI wystarczy przełączyć protokół z FTP na FTPS (Explicit TLS) i ręcznie zaakceptować certyfikat.
• Bezpieczeństwo: rejectUnauthorized: false wyłącza weryfikację certyfikatu, jest to dopuszczalne tylko dla serwerów deweloperskich i środowisk testowych, nigdy na produkcji.

Skąd bierze się błąd SSL/TLS required on the data channel

Protokół FTP działa przez dwa kanały: kanał kontrolny (polecenia) i kanał danych (właściwe przesyłanie plików). Gdy serwer jest skonfigurowany na FTPS (FTP over TLS), szyfruje oba. Klient, który próbuje połączyć się zwykłym FTP, pomyślnie przechodzi uwierzytelnianie na kanale kontrolnym, ale podczas próby otwarcia kanału danych serwer odpowiada: 550 SSL/TLS required on the data channel.

Przyczyna techniczna leży w implementacji TLS po stronie Node.js (na którym napisane są zarówno Remote FTP dla Atoma, jak i rozszerzenie SFTP dla VS Code). Node.js domyślnie sprawdza ważność certyfikatu SSL. Certyfikat z podpisem własnym (self-signed) nie przechodzi tej weryfikacji, połączenie jest zrywane. Rozwiązanie: albo jawnie wskazać klientowi, że certyfikat nie ma być sprawdzany (rejectUnauthorized: false), albo przełączyć się na jawny FTPS z ręczną akceptacją certyfikatu.

Rozwiązanie 1: prawidłowy.ftpconfig dla Atom i Pulsar

Atom został oficjalnie zamknięty w grudniu 2022, ale jego fork Pulsar (dawny Atom) jest w pełni kompatybilny z pakietami Atoma, w tym z Remote FTP. Rozwiązanie polega na wpisaniu poprawnych secureOptions w .ftpconfig.

Proszę utworzyć (lub edytować) plik .ftpconfig w katalogu głównym projektu:

1
{
2
    "protocol": "ftp",
3
    "host": "ваш.сервер.com",
4
    "port": 21,
5
    "user": "логин",
6
    "pass": "пароль",
7
    "promptForPass": false,
8
    "remote": "/",
9
    "secure": true,
10
    "secureOptions": {
11
        "rejectUnauthorized": false
12
    },
13
    "connTimeout": 10000,
14
    "keepalive": 10000
15
}

Kluczowe parametry:

• secure: true, włącza TLS dla kanałów kontrolnego i danych;
• rejectUnauthorized: false, wyłącza weryfikację certyfikatu (Node.js przestaje wymagać ważnego certyfikatu od serwera);
• port: 21, standardowy port dla FTP; dla FTPS przez implicit TLS proszę użyć portu 990 i protocol: "ftps".

Po zapisaniu .ftpconfig proszę ponownie połączyć się z serwerem, błąd SSL/TLS required on the data channel zniknie.

Rozwiązanie 2: konfiguracja rozszerzenia SFTP w VS Code

Najpopularniejsze rozszerzenie do FTP/SFTP w VS Code, SFTP od liximomo (1,3+ mln instalacji). Błąd 550 SSL/TLS required on the control channel został w nim omówiony w zgłoszeniu #872.

Po zainstalowaniu rozszerzenia proszę wykonać Ctrl+Shift+P → SFTP: Config, otworzy się plik sftp.json. Proszę doprowadzić go do następującej postaci:

1
{
2
    "name": "Мой сервер",
3
    "host": "ваш.сервер.com",
4
    "protocol": "ftp",
5
    "port": 21,
6
    "secure": true,
7
    "username": "логин",
8
    "password": "пароль",
9
    "remotePath": "/",
10
    "uploadOnSave": true
11
}

Parametr secure: true jest bezpośrednim odpowiednikiem rejectUnauthorized: false z .ftpconfig. Mówi on rozszerzeniu, aby używało FTPS i nie zrywało połączenia przy samopodpisanym certyfikacie.

Jeśli serwer używa implicit FTPS (port 990), proszę zamienić protocol na ftps i port na 990. Proszę zapisać sftp.json, wykonać SFTP: Download Project, rozszerzenie połączy się i pobierze zawartość remotePath.

Rozwiązanie 3: FileZilla i inne klienty GUI

W klientach GUI problem rozwiązuje się jeszcze prościej, na poziomie interfejsu. W FileZilla:

• Proszę otworzyć Menedżera Stron (Ctrl+S).
• Proszę wybrać połączenie, w polu Protokół przełączyć z FTP na FTP over TLS (explicit).
• Przy pierwszym połączeniu FileZilla pokaże okno dialogowe z odciskiem certyfikatu, proszę nacisnąć Zaufaj temu certyfikatowi i zaznaczyć „Zawsze ufaj".

Ta sama zasada działa w WinSCP, Cyberduck i każdym nowoczesnym kliencie FTP: proszę jawnie wskazać protokół FTPS i ręcznie zaakceptować certyfikat. Żadnych plików konfiguracyjnych, tylko interfejs.

Kiedy NIE należy wyłączać weryfikacji certyfikatu

rejectUnauthorized: false to świadome osłabienie bezpieczeństwa. Mówi Pan/Pani klientowi: „akceptuj KAŻDY certyfikat, nawet podrobiony". Jest to dopuszczalne w trzech przypadkach:

• Lokalny serwer deweloperski lub środowisko stagingowe, niedostępne z internetu.
• Pana/Pani własny VPS, gdzie dokładnie zna Pan/Pani pochodzenie certyfikatu.
• Środowisko testowe za firmowym VPN.

Na serwerze produkcyjnym z samopodpisanym certyfikatem lepiej poświęcić 15 minut i skonfigurować Let's Encrypt, bezpłatny certyfikat SSL, który jest uznawany przez wszystkich klientów bez rejectUnauthorized: false.

Proszę obejrzeć krótki poradnik dotyczący połączenia SFTP w VS Code, wszystkie kroki od instalacji rozszerzenia do pierwszego połączenia z serwerem:

⁉️🤔 Często zadawane pytania

Błąd pozostał po secure: true, co jeszcze sprawdzić?

W pierwszej kolejności proszę zweryfikować port. Explicit FTPS działa na porcie 21, implicit na 990. Jeśli serwer administratora wymaga implicit FTPS, a Pan/Pani wskazał protocol: "ftp" z port: 21, połączenie nie zostanie nawiązane, niezależnie od zmian secureOptions. Proszę sprawdzić w panelu hostingowym lub zapytać administratora, jaki dokładnie tryb FTPS jest na serwerze.

Czy można użyć SFTP zamiast FTPS?

Tak i jest to lepsza opcja. SFTP (SSH File Transfer Protocol) działa na bazie SSH, a nie FTP, dlatego problem z certyfikatami SSL w ogóle dla niego nie istnieje. Jeśli serwer udostępnia dostęp SSH, proszę używać SFTP, a nie FTPS. W tym samym .ftpconfig wystarczy zmienić protocol na sftp i port na 22.

Atom został zamknięty, Remote FTP jeszcze działa?

Pakiet Remote FTP jest dostępny w repozytorium Atoma, ale sam edytor nie jest aktualizowany od grudnia 2022 i zawiera znane podatności. GitHub cofnął nawet certyfikaty podpisywania kodu dla Atoma w styczniu 2023. Jeśli Atom jeszcze się Panu/Pani uruchamia, proszę migrować na fork Pulsar, obsługuje on te same pakiety i konfiguracje bez zmian.

A co z VS Code Remote SSH?

Remote SSH to doskonała alternatywa dla połączeń FTP, jeśli serwer jest na Linuxie i jest dostęp SSH. Pracuje Pan/Pani z plikami bezpośrednio, bez synchronizacji i kłopotów z certyfikatami. Jednak dla hostingów współdzielonych, gdzie SSH jest zamknięty, a dostęp jest tylko przez FTP, rozwiązania z tego posta pozostają aktualne.

Błąd SSL/TLS required on the control channel (nie data channel), czy to to samo?

Tak, różnica dotyczy tylko kanału, na którym nastąpiło zerwanie. Kanał kontrolny to kanał poleceń (uwierzytelnianie, nawigacja), kanał danych to przesyłanie plików. Serwer może wymagać TLS na każdym z nich. Rozwiązanie jest identyczne: secure: true + rejectUnauthorized: false w konfiguracji.

Błąd pozostał: końcowa lista kontrolna

Proszę przejść przez punkty, jeden z nich rozwiąże problem:

• Protokół, czy secure: true jest ustawione w konfiguracji (.ftpconfig lub sftp.json)?
• Port, explicit FTPS = 21, implicit = 990, SFTP = 22. Proszę porównać z ustawieniami serwera.
• rejectUnauthorized, samopodpisany certyfikat bez tej opcji NIE przejdzie weryfikacji Node.js.
• Klient GUI, czy przełączono Menedżera Stron na FTP over TLS (explicit) i ręcznie zaakceptowano certyfikat?
• SFTP zamiast FTPS, jeśli jest dostęp SSH, proszę zapomnieć o FTP i przejść na SFTP.

Jeśli wszystko zostało wypróbowane, a błąd nadal występuje, najprawdopodobniej serwer jest skonfigurowany na implicit FTPS (port 990), a klient łączy się na 21. Proszę doprecyzować u dostawcy hostingu wymagany tryb i port.

Ten błąd nie jest błędem edytora, lecz cechą uzgadniania TLS z samopodpisanym certyfikatem. Po prawidłowej konfiguracji znika on na każdym kliencie: czy to w Atomie z 2018 roku, czy w Pulsarze z 2026, czy w VS Code.