andspace/ftp-anon repository overview

⁠📁 FTP Anonymous Server

A lightweight Docker container running an FTP server with anonymous access for file uploads and downloads, built on Alpine Linux for minimal footprint. 🚀

GitHub Repository: logical-and/ftp-anon⁠

⁠🚀 Quick Start

⁠Basic Usage

docker run -it --rm -p 21:21 -p 30000-30100:30000-30100 andspace/ftp-anon

⁠Real-world Example

port=2121; pasv_from=$((port+1)); pasv_to=$((port+10)); \
docker run -it --rm \
  -v $(pwd):/var/ftp/public \
  -p "$port":"$port" \
  -p "$pasv_from"-"$pasv_to":"$pasv_from"-"$pasv_to" \
  -e PORT="$port" \
  -e PASSIVE_MIN_PORT="$pasv_from" \
  -e PASSIVE_MAX_PORT="$pasv_to" \
  -e LOG_LEVEL=MINIMAL \
  andspace/ftp-anon

⁠With All Options

docker run -it --rm \
  -p 2121:2121 -p 35000-35100:35000-35100 \
  -v $(pwd):/var/ftp/public \
  -e EXTERNAL_IP=192.168.1.100 \
  -e PORT=2121 \
  -e PASSIVE_ENABLE=YES \
  -e PASSIVE_MIN_PORT=35000 \
  -e PASSIVE_MAX_PORT=35100 \
  -e FTP_UID=1000 \
  -e FTP_GID=1000 \
  -e LOCAL_UMASK=022 \
  -e MAX_CLIENTS=50 \
  -e MAX_PER_IP=5 \
  -e IDLE_TIMEOUT=600 \
  -e DATA_TIMEOUT=120 \
  -e TTL=10 \
  -e LISTEN_ADDRESS= \
  -e MAX_UPLOAD_RATE=0 \
  -e MAX_DOWNLOAD_RATE=0 \
  -e MAX_FILE_SIZE=0 \
  -e ALLOW_DELETE=YES \
  -e ALLOW_OVERWRITE=YES \
  -e DIR_UMASK=022 \
  -e LOG_LEVEL=VERBOSE \
  -e BANNER_TEXT="Custom Welcome Message" \
  -e ASCII_MODE=YES \
  -e USE_SENDFILE=YES \
  andspace/ftp-anon

⁠✨ Features

• 🔓 Anonymous Access: No authentication required
• 📤 Upload/Download: Anonymous users can list, upload, and download files
• 🏔️ Alpine-based: Minimal footprint using Alpine Linux
• 🌐 Auto IP Detection: Automatically detects external IP using api.ipify.org
• 🔧 Auto Ownership & Permission Preservation: Automatically detects and preserves mounted directory ownership and permissions
• 💬 Smart Banner: Environment-aware banner with relevant server info
• ⚙️ Highly Configurable: All settings via environment variables
• 📝 Intelligent Logging: Multi-level logging (INFO/DEBUG) with startup connection details
• 🔍 Enhanced Startup: Complete connection information displayed at server start
• 📦 Self-contained: No external directories required

⁠🔧 Environment Variables

⁠⚡ Core Settings

⁠🔐 Connection & Security

⁠🚀 Transfer Limits

⁠📁 File Operations

⁠📊 Logging & Display

⁠⚡ Performance

⁠📖 Usage

1. 🔗 Connect to FTP: Use any FTP client and connect to the server IP on the configured port
2. 👤 Anonymous Login: Username: anonymous, Password: (any email or leave blank)
3. 📤 Upload Files: Navigate to /public directory to upload files
4. 📥 Download Files: Browse and download any files in the FTP directory

⁠🎯 Smart Banner & Startup Info

⁠Connection Banner

When you connect via FTP, you'll see a clean, environment-aware banner:

Welcome to Anonymous FTP Server! 🎉 | 📁 Upload to /public/ | 🌐 Server: 203.0.113.1 | 💾 Happy file sharing!

The banner automatically includes relevant environment information like server IP, custom ports, or TTL when they differ from defaults.

⁠Startup Connection Details

When the server starts, you'll see complete connection information in the logs:

[2025-08-14 17:36:17] [INFO] === 🚀 FTP Server Started Successfully! ===
[2025-08-14 17:36:17] [INFO] 
[2025-08-14 17:36:17] [INFO] 📋 Connection Information:
[2025-08-14 17:36:17] [INFO] 🌐 Server IP: 203.0.113.1
[2025-08-14 17:36:17] [INFO] 🔌 Port: 2121
[2025-08-14 17:36:17] [INFO] 🔗 Quick Connect URL: ftp://[email protected]:2121/public/
[2025-08-14 17:36:17] [INFO] 👤 Username: anonymous
[2025-08-14 17:36:17] [INFO] 🔑 Password: (any email address or leave blank)
[2025-08-14 17:36:17] [INFO] 📂 Upload directory: /public/

⁠💻 Example FTP Client Commands

# Using command-line FTP client
ftp <server-ip> 2121
# Username: anonymous
# Password: (press enter or type any email)

# List files
ls

# Change to upload directory
cd public

# Upload a file
put myfile.txt

# Download a file
get somefile.txt

⁠📂 Directory Structure

• /var/ftp/ - FTP root directory (read-only)
• /var/ftp/public/ - Upload directory for anonymous users (writable)

⁠🔌 Ports

• 21: Default FTP control port
• 30000-30100: Default passive mode data ports
• Configure custom ports using environment variables

⁠🌐 IP Detection

The server automatically detects your external IP using the api.ipify.org service and includes it in the welcome banner. You can override this by setting the EXTERNAL_IP environment variable.

⁠🔧 File Ownership & Permission Preservation

When mounting local directories, Docker may change file ownership and permissions which can be problematic. The container automatically detects and preserves both the ownership and permissions of your mounted directory:

# Automatic ownership & permission detection (recommended)
docker run -it --rm \
  -v $(pwd):/var/ftp/public \
  andspace/ftp-anon

The container automatically detects:

• UID/GID: User and group ownership of the mounted directory
• Permissions: Exact permission mode (e.g., 755, 750, 644, etc.)

This ensures your local directory maintains its original ownership and access permissions, preventing permission issues.

You can also manually specify custom IDs if needed:

# Manual UID/GID specification (optional)
docker run -it --rm \
  -v $(pwd):/var/ftp/public \
  -e FTP_UID=1000 \
  -e FTP_GID=1000 \
  andspace/ftp-anon

This prevents Docker from changing your local directory ownership to the container's default FTP user (UID 21) and ensures proper access control.

⁠📝 Intelligent Logging

The container provides multi-level logging with smart verbosity control:

⁠Log Levels

• VERBOSE (Default): Complete configuration details, debug info, and all operational information
• MINIMAL: Essential startup info, connection details, configuration summary, and errors only

⁠Usage

# Default logging (VERBOSE level - shows all details)
docker run -it --rm andspace/ftp-anon

# Minimal logging (essential info only)
docker run -it --rm -e LOG_LEVEL=MINIMAL andspace/ftp-anon

# View logs
docker logs <container-name>

# Real-time log monitoring
docker logs -f <container-name>

⁠What You'll See

VERBOSE Level (Default): Complete configuration details, debug info, and all operational information
MINIMAL Level: Clean startup with essential connection details and configuration summary only

⁠🔒 Security Notes

• This server allows anonymous access with upload capabilities
• Intended for development/testing environments
• For production use, consider additional security measures
• No authentication or encryption is provided
• The FTP root directory is read-only for security
• Only the public/ subdirectory allows uploads