Raspberry Pi as FTP Server: Hardware Picks, TLS Setup, and Debugging

To run a reliable, secure Raspberry Pi as FTP server, use a Raspberry Pi 4 Model B (4GB) paired with a USB 3.0 SSD, configure vsftpd with TLS encryption, and isolate user directories with chroot jails. Plain FTP transmits credentials in cleartext, making FTPS (FTP over SSL/TLS) mandatory for any device exposed to a network. This guide walks through the exact hardware selection, secure daemon configuration, GPIO-based disk monitoring, and the specific debugging steps required when the daemon inevitably throws chroot errors.

Decision Tree: Picking the Right Board Variant

Not every Raspberry Pi is suited for 24/7 network-attached storage duties. Thermal throttling, shared bus architectures, and idle power draw dictate which board survives long-term FTP workloads.

Hardware Spec Sheet and GPIO Pin Mapping

Before flashing the OS, gather the exact components. The code and configurations in this guide target the Pi 4 4GB running Raspberry Pi OS Bookworm (64-bit).

Parts List

• Compute: Raspberry Pi 4 Model B (4GB RAM) - ~$55 USD
• Storage: Samsung T7 Shield 1TB USB 3.2 SSD - ~$90 USD (Do not use cheap thumb drives; they drop offline under sustained FTP write caching).
• Power: Official Raspberry Pi 27W USB-C Power Supply (Ensures no low-voltage warnings when the SSD spins up).
• Indicator: Standard 5mm Red LED with a 330Ω current-limiting resistor.

Pin Mapping Table: Disk Warning LED

We will wire a physical LED to alert you when the FTP upload directory nears capacity, visible from across the workbench without needing to SSH in.

Installing vsftpd and Enforcing FTPS (FTP over TLS)

Never run plain FTP. We will use vsftpd (Very Secure FTP Daemon) and force TLS encryption. For deeper context on securing Linux file transfers, refer to the DigitalOcean vsftpd configuration guide.

1. Install the daemon:
   sudo apt update && sudo apt install vsftpd openssl -y
2. Generate a self-signed TLS certificate:
   sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/ssl/private/vsftpd.pem -out /etc/ssl/certs/vsftpd.pem
   (Press Enter through the prompts; the Common Name doesn't matter for local LAN use).
3. Backup and edit the configuration:
   sudo cp /etc/vsftpd.conf /etc/vsftpd.conf.bak
sudo nano /etc/vsftpd.conf
4. Apply these exact parameters to vsftpd.conf:

   listen=NO
   listen_ipv6=YES
   anonymous_enable=NO
   local_enable=YES
   write_enable=YES
   chroot_local_user=YES
   user_sub_token=$USER
   local_root=/home/$USER/ftp
   pasv_enable=YES
   pasv_min_port=30000
   pasv_max_port=30100
   userlist_enable=YES
   userlist_file=/etc/vsftpd.userlist
   userlist_deny=NO
   ssl_enable=YES
   rsa_cert_file=/etc/ssl/certs/vsftpd.pem
   rsa_private_key_file=/etc/ssl/private/vsftpd.pem
   allow_anon_ssl=NO
   force_local_data_ssl=YES
   force_local_logins_ssl=YES
   ssl_tlsv1=YES
   ssl_sslv2=NO
   ssl_sslv3=NO
   require_ssl_reuse=NO
   ssl_ciphers=HIGH

5. Create the user and directory structure:
   sudo adduser ftpuser
sudo mkdir -p /home/ftpuser/ftp/uploads
sudo chown nobody:nogroup /home/ftpuser/ftp
sudo chmod a-w /home/ftpuser/ftp
sudo chown ftpuser:ftpuser /home/ftpuser/ftp/uploads
echo 'ftpuser' | sudo tee -a /etc/vsftpd.userlist
6. Restart the service:
   sudo systemctl restart vsftpd

Automating Disk Monitoring with Python and GPIO

Headless servers fail silently when disks fill up. This Python script monitors the FTP upload directory and triggers the GPIO 17 LED when usage exceeds 90%. It uses the gpiozero library, which is pre-installed on Raspberry Pi OS. For more on Pi hardware interfaces, check the official Raspberry Pi hardware documentation.

#!/usr/bin/env python3
"""
FTP Directory Disk Space Monitor for Raspberry Pi
Targets: Raspberry Pi 4 Model B (4GB) / Pi OS Bookworm
"""
import shutil
import time
import sys
from gpiozero import LED

# PIN DEFINITIONS
DISK_WARN_LED_PIN = 17  # Physical Pin 11, BCM GPIO 17

# CONFIGURATION
FTP_DIR = "/home/ftpuser/ftp/uploads"
THRESHOLD_PERCENT = 90.0
CHECK_INTERVAL_SEC = 60

warn_led = LED(DISK_WARN_LED_PIN)

def check_disk_space():
    try:
        total, used, free = shutil.disk_usage(FTP_DIR)
        used_percent = (used / total) * 100
        
        if used_percent >= THRESHOLD_PERCENT:
            if not warn_led.is_lit:
                print(f"WARNING: Disk usage at {used_percent:.1f}%. Triggering GPIO {DISK_WARN_LED_PIN}.")
                warn_led.on()
        else:
            if warn_led.is_lit:
                print(f"OK: Disk usage at {used_percent:.1f}%. Clearing GPIO {DISK_WARN_LED_PIN}.")
                warn_led.off()
                
    except FileNotFoundError:
        print(f"ERROR: Directory {FTP_DIR} not found. Check your vsftpd mount.")
        # Fast blink indicates missing directory / unmounted SSD
        warn_led.blink(on_time=0.2, off_time=0.2)
    except PermissionError:
        print(f"ERROR: Permission denied reading {FTP_DIR}. Run with sudo or fix ownership.")
        warn_led.off()
    except Exception as e:
        print(f"CRITICAL ERROR reading disk: {e}")
        sys.exit(1)

if __name__ == "__main__":
    try:
        print(f"Monitoring {FTP_DIR} every {CHECK_INTERVAL_SEC}s...")
        while True:
            check_disk_space()
            time.sleep(CHECK_INTERVAL_SEC)
    except KeyboardInterrupt:
        print("\nShutting down monitor and cleaning up GPIO.")
        warn_led.off()
        sys.exit(0)

Save this as ftp_monitor.py and run it via a systemd service so it survives reboots. The try/except blocks ensure that if your USB SSD drops offline (a common occurrence with underpowered supplies), the script won't crash; instead, it will fast-blink the LED to indicate a missing mount point.

Debugging: The "500 OOPS" Chroot Error

When configuring chroot jails, you will almost certainly encounter this exact error string when attempting to log in via your FTP client:

Ranked Causes and Fixes

1. Cause: Security Patch Restriction (Most Likely). Modern versions of vsftpd prevent users from having write access to the root of their chroot directory to prevent privilege escalation exploits.
   Fix A (The Secure Way): Ensure the chroot root (/home/ftpuser/ftp) is owned by nobody:nogroup and has a-w permissions, while the subdirectory (/uploads) is owned by ftpuser. (This is what we did in Step 5 above).
   Fix B (The Quick Way): If you are on an isolated LAN and just want it to work, add allow_writeable_chroot=YES to the bottom of /etc/vsftpd.conf and restart the daemon.
2. Cause: SELinux or AppArmor Interference. If you are running a strict security module, it may block the chroot pivot.
   Fix: Check sudo dmesg | grep vsftpd for denied MAC (Mandatory Access Control) logs and adjust the profile accordingly.
3. Cause: Typo in local_root. The path in vsftpd.conf doesn't match the actual filesystem path.
   Fix: Verify local_root matches the exact directory created in Step 5.

The First Three Things to Check When Connections Fail

If the daemon is running but your FTP client (like FileZilla) times out or refuses the connection, check these three items in order:

1. Passive Port Firewall Blocks: FTP uses Port 21 for commands, but transfers use random high ports. We restricted these to 30000-30100 in the config. If UFW (Uncomplicated Firewall) is active on the Pi, you must explicitly open them:
   sudo ufw allow 30000:30100/tcp
2. NAT / pasv_address Mismatch: If you are accessing the FTP server from outside your local network (via port forwarding), the Pi will incorrectly hand out its local IP (e.g., 192.168.1.50) to the client for the data connection. You must add pasv_address=YOUR_PUBLIC_IP to vsftpd.conf.
3. TLS Certificate Permissions: The vsftpd process drops root privileges after binding to port 21. If the /etc/ssl/private/vsftpd.pem file is strictly owned by root with 600 permissions, the daemon will fail to initiate the TLS handshake. Ensure the certificate is readable by the vsftpd service group.

How to Extend or Simplify the Build

Depending on your actual network topology, you may not need FTP at all.

To Simplify: Switch to SFTP

If you only need to transfer files securely and don't have legacy hardware that strictly requires the FTP protocol, delete vsftpd and use SFTP. SFTP (SSH File Transfer Protocol) is built directly into the Raspberry Pi's OpenSSH server. It requires zero extra configuration, uses standard Port 22, handles encryption natively, and completely bypasses the passive port firewall nightmares inherent to FTPS. Just enable SSH via sudo raspi-config and connect using your standard Pi credentials.

To Extend: Add Brute-Force Protection

If you must expose Port 21 to the internet, install fail2ban. Configure a jail for vsftpd to monitor /var/log/vsftpd.log. Set it to ban IP addresses for 24 hours after 3 failed login attempts. FTP is a legacy protocol heavily targeted by automated botnets; running it on the open web without fail2ban will result in your Pi's CPU spiking as it processes thousands of dictionary attacks per hour.