Skip to content

README.md

Latest commit

 

History

History
185 lines (137 loc) · 6.43 KB

README.md

File metadata and controls

185 lines (137 loc) · 6.43 KB

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
  1. Install dependencies:
pip install -r requirements.txt
  1. 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.