0
# FTP Servers
1

2
Server implementations providing different concurrency models for building scalable FTP services. pyftpdlib offers asynchronous, multi-threaded, and multi-process server options to handle various performance requirements and deployment scenarios.
3

4
## Capabilities
5

6
### Basic FTP Server
7

8
Main asynchronous FTP server using single-process event-driven architecture for maximum efficiency and scalability.
9

10
```python { .api }
11
class FTPServer:
12
    # Class attributes
13
    max_cons: int = 512
14
    max_cons_per_ip: int = 0  # 0 = unlimited
15
    
16
    def __init__(self, address_or_socket, handler, ioloop=None, backlog=100):
17
        """
18
        Initialize FTP server.
19
        
20
        Parameters:
21
        - address_or_socket: tuple (host, port) or socket object
22
        - handler: FTPHandler class or subclass
23
        - ioloop: IOLoop instance (None = use default)
24
        - backlog: maximum queued connections
25
        """
26
    
27
    @property
28
    def address(self):
29
        """Get server listening address as (host, port) tuple."""
30
    
31
    def serve_forever(self, timeout=None, blocking=True, handle_exit=True, worker_processes=1):
32
        """
33
        Start serving requests.
34
        
35
        Parameters:
36
        - timeout: I/O polling timeout in seconds
37
        - blocking: whether to block until server stops
38
        - handle_exit: whether to handle SIGINT/SIGTERM signals
39
        - worker_processes: number of processes to fork (POSIX only)
40
        """
41
    
42
    def handle_accepted(self, sock, addr):
43
        """Handle new client connection."""
44
    
45
    def close_all(self):
46
        """Close server and all client connections."""
47
    
48
    # Context manager support
49
    def __enter__(self): ...
50
    def __exit__(self, *args): ...
51
```
52

53
### Multi-threaded Server
54

55
Multi-threaded server that spawns a new thread for each client connection, suitable for I/O-bound operations or when using blocking filesystem operations.
56

57
```python { .api }
58
class ThreadedFTPServer(FTPServer):
59
    # Class attributes
60
    poll_timeout: float = 1.0
61
    join_timeout: int = 5
62
    refresh_interval: int = 5
63
    
64
    def __init__(self, address_or_socket, handler, ioloop=None, backlog=100):
65
        """Initialize threaded FTP server with same parameters as FTPServer."""
66
```
67

68
### Multi-process Server
69

70
Multi-process server that forks worker processes to handle client connections, providing true parallelism and fault isolation. Available on POSIX systems only.
71

72
```python { .api }
73
class MultiprocessFTPServer(FTPServer):  # POSIX only
74
    # Class attributes  
75
    poll_timeout: float = 1.0
76
    join_timeout: int = 5
77
    refresh_interval: int = 5
78
    
79
    def __init__(self, address_or_socket, handler, ioloop=None, backlog=100):
80
        """Initialize multi-process FTP server with same parameters as FTPServer."""
81
```
82

83
## Usage Examples
84

85
### Basic Single-Process Server
86

87
```python
88
from pyftpdlib.authorizers import DummyAuthorizer
89
from pyftpdlib.handlers import FTPHandler
90
from pyftpdlib.servers import FTPServer
91

92
# Setup authorizer and handler
93
authorizer = DummyAuthorizer()
94
authorizer.add_user("user", "pass", "/home/user", perm="elradfmwMT")
95

96
handler = FTPHandler
97
handler.authorizer = authorizer
98

99
# Create and start server
100
server = FTPServer(("0.0.0.0", 21), handler)
101
server.serve_forever()
102
```
103

104
### Multi-threaded Server
105

106
```python
107
from pyftpdlib.servers import ThreadedFTPServer
108

109
# Same setup as above...
110
server = ThreadedFTPServer(("0.0.0.0", 21), handler)
111
server.serve_forever()
112
```
113

114
### Multi-process Server with Worker Processes
115

116
```python
117
from pyftpdlib.servers import MultiprocessFTPServer
118

119
# Same setup as above...
120
server = MultiprocessFTPServer(("0.0.0.0", 21), handler)
121

122
# Fork 4 worker processes
123
server.serve_forever(worker_processes=4)
124
```
125

126
### Context Manager Usage
127

128
```python
129
with FTPServer(("0.0.0.0", 21), handler) as server:
130
    print(f"Starting FTP server on {server.address}")
131
    server.serve_forever()
132
```
133

134
### Connection Limits
135

136
```python
137
# Limit total connections and per-IP connections
138
class CustomFTPServer(FTPServer):
139
    max_cons = 256           # Maximum 256 total connections
140
    max_cons_per_ip = 5      # Maximum 5 connections per IP
141

142
server = CustomFTPServer(("0.0.0.0", 21), handler)
143
server.serve_forever()
144
```
145

146
### Signal Handling
147

148
```python
149
import signal
150

151
def signal_handler(signum, frame):
152
    print(f"Received signal {signum}, shutting down...")
153
    server.close_all()
154

155
server = FTPServer(("0.0.0.0", 21), handler)
156

157
# Custom signal handling
158
signal.signal(signal.SIGINT, signal_handler)
159
signal.signal(signal.SIGTERM, signal_handler)
160

161
# Start server without built-in signal handling
162
server.serve_forever(handle_exit=False)
163
```
164

165
## Performance Considerations
166

167
- **FTPServer**: Best for most use cases, handles thousands of concurrent connections efficiently
168
- **ThreadedFTPServer**: Use when handlers perform blocking I/O operations or CPU-intensive tasks
169
- **MultiprocessFTPServer**: Use for maximum throughput and fault isolation, requires more system resources
170

171
## Platform Support
172

173
- **FTPServer**: All platforms (Windows, Linux, macOS, etc.)
174
- **ThreadedFTPServer**: All platforms
175
- **MultiprocessFTPServer**: POSIX systems only (Linux, macOS, BSD, etc.)