Simple Python FTP Server for Scanning Devices

A lightweight, configurable FTP server designed specifically for receiving scanned documents from MFP devices. Built with Python and pyftpdlib, it supports both background daemon mode and interactive console operation with real-time configuration.

⚠️ Current Status: Stable Beta

Core functionality is production-ready and tested with MFP devices. The server is stable for everyday use but has known technical issues that require resolution.

✨ Features

• Dual Operation Modes: Run as a background daemon process or interactive console application
• Automatic Configuration: Self-initializing configuration file with secure random credentials
• User Management: Multiple user accounts with customizable permissions and access control
• Transfer Modes: Configurable passive and active data transfer modes
• Anonymous Access: Optional anonymous FTP access with restricted permissions
• Cross-Platform: Works on Windows, Linux, and macOS (tested primarily on Windows 10, additional testing required for other OSes)

🚀 Getting Started

Prerequisites

• Python 3.7 or higher
• pip package manager

Installation

1. Clone the repository:

git clone https://github.com/your-username/python-ftp-server.git
cd python-ftp-server

2. Install dependencies:

pip install -r requirements.txt

3. Run the server for the first time (auto-generates config):

python src/ftp_server.py

Configuration

The server automatically creates configuration file on first run with:

• Secure random admin credentials (displayed in console)
• Default port 2121
• Passive ports range 60000-60100
• Safe default permissions

Edit the configuration file to customize:

• Server network settings (IP, ports)
• User accounts and access permissions
• Operational mode preferences

Building Executable

Create a standalone Windows executable:

pyinstaller --onefile --console src/ftp_server.py

📖 Usage

Console Mode (Interactive)

python src/ftp_server.py --console

Background Daemon Mode

# Start as background process
python src/ftp_server.py --service-start

# Stop running background process
python src/ftp_server.py --service-stop

Command Line Options

• --console: Force interactive console mode operation
• --service-start: Start as background daemon process
• --service-stop: Stop running background process
• --service-worker: Internal parameter for worker process

🔧 Configuration Management

Interactive console provides real-time management for:

• Server network settings and port configuration
• User account management (create, modify, delete)
• Permission control and access restrictions
• Operational mode settings

📝 Supported FTP Features

• Standard FTP protocol implementation
• Both active and passive transfer modes
• User authentication
• Directory listing and file operations
• Configurable data port ranges

🐛 Known Technical Issues and Limitations

Architectural Issues

• SOLID principles violations - classes have too many responsibilities
• Mixed concerns - business logic mixed with configuration management

Security Issues

• Password hashing incomplete - implementation needs proper salting and storage
• Plaintext passwords stored even when hashing is configured
• Input validation missing for interactive mode user inputs

Windows-Specific Issues

• Not a true Windows Service - background mode uses daemon process only
• PID file race conditions potential issues in service management
• Unreliable PID detection on Windows systems
• Path handling issues with backslashes in some scenarios

Performance Concerns

• Configuration parsing overhead - multiple re-parsing without caching
• Blocking operations in main thread affecting responsiveness
• No connection pooling for multiple simultaneous connections

Code Quality Issues

• Code duplication across multiple modules
• Magic numbers without proper documentation
• Hardcoded values for timeouts and restart limits
• Resource management potential memory leaks
• Encoding issues possible on different platforms

🗺️ Development Roadmap

High Priority Fixes

• Fix critical issues identified in the current version
• Complete password hashing implementation with proper salting
• Add input validation for interactive mode
• Fix PID file race conditions and Windows process detection

Medium Priority Improvements

• Refactor classes to follow SOLID principles
• Separate business logic from configuration management
• Add proper error handling and comprehensive logging
• Implement retry logic for critical operations
• Fix threading issues and add proper timeouts

Code Quality Enhancements

• Add proper signal handling for different modes
• Fix encoding issues for cross-platform compatibility
• No log rotation - Log files can grow indefinitely. Need to add rotation and corresponding settings via configuration file
• No health-check mechanism - Need to implement server health monitoring

🤝 Contributing

We welcome contributions! Please feel free to submit pull requests, report bugs, or suggest new features.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🆘 Troubleshooting

Common Issues

• Port already in use: Change default port in configuration
• Permission denied: Check directory permissions
• Connection timeout: Verify firewall settings and passive port ranges

Getting Help

• Check existing Issues for similar problems
• Create a new Issue with detailed description of your problem
• Include server logs and configuration details (without passwords)

📜 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

🙏 Acknowledgments

• Built on pyftpdlib - extremely fast and scalable Python FTP server library
• Inspired by real-world document management processes

---

Note: This software is stable for production use with MFP devices but has known technical issues planned for resolution in future versions.

Passwords are stored in plain text - secure the configuration file.