|
FAQ
Frequently Asked Questions
Table of contents¶
Introduction¶What is pyftpdlib?¶pyftpdlib is a high-level library to easily write asynchronous portable FTP servers with Python. What is Python?¶Python is an interpreted, interactive, object-oriented, easy-to-learn programming language. It is often compared to Tcl, Perl, Scheme or Java. I'm not a python programmer. Can I use it anyway?¶Yes. pyftpdlib is a fully working FTP server implementation that can be run "as is". For example you could run an anonymous ftp server from cmd-line by running: giampaolo@ubuntu:~$ sudo python -m pyftpdlib.ftpserver Serving FTP on 0.0.0.0:21 This is useful in case you want a quick and dirty way to share a directory without, say, installing and configuring samba. Starting from version 0.6.0 options can be passed to the command line (see python -m pyftpdlib.ftpserver --help to see all available options). Examples: Anonymous FTP server with write access: giampaolo@ubuntu:~$ sudo python -m pyftpdlib.ftpserver -w /usr/local/lib/python2.6/site-packages/pyftpdlib/ftpserver.py:520: RuntimeWarning: Write permissions assigned to anonymous user. RuntimeWarning) Serving FTP on 0.0.0.0:21 Listen on a different ip/port: giampaolo@ubuntu:~$ python -m pyftpdlib.ftpserver -i 127.0.0.1 -p 8021 Serving FTP on 127.0.0.1:8021 Customizing ftpd for basic tasks like adding users or deciding where log file should be placed is mostly simply editing variables. This is basically like learning how to edit a common unix ftpd.conf file and doesn't really require Python knowledge. Customizing ftpd more deeply requires a python script which imports pyftpdlib to be written separately. An example about how this could be done are the scripts contained in the demo directory. Documentation¶http://code.google.com/p/pyftpdlib/ is the primary source for all information about the project including Install instructions, Tutorial, RFCs Compliance paper, Wikis and the Bug Tracker. Mailing lists¶There are a number of mailing lists for pyftpdlib:
Bug reporting¶Bug reports should be made via Google Code Issue Tracker. Patches should be attached to the appropriate bug and not mailed directly to the mailing lists or any given team member. Installing and compatibility¶How do I install pyftpdlib?¶If you are not new to Python you probably don't need that, otherwise follow the instructions. Which Python versions are compatible?¶2.4, 2.5, 2.6 and 2.7. Python 2.3 support has been removed starting from version 0.6.0. The latest version supporting Python 2.3 is pyftpdlib 0.5.2. What about Python 3.x?¶Python 3.x is not yet covered because I still have to figure out how to deal with the str/bytes and encoding differences introduced in the new Python version =). A porting to Python 3.x is surely in plan, anyway (see issue #76. On which platforms can pyftpdlib be used?¶pyftpdlib should work on any platform where select() or poll() system calls are available and on any Python implementation which refers to cPython 2.4 or superior (e.g cPython 2.6 or PythonCE 2.5). The development team has mainly tested it under various Linux, Windows, OS X and FreeBSD systems. For FreeBSD is also available a pre-compiled package maintained by Li-Wen Hsu <lwhsu@freebsd.org>. Other Python implementation like PythonCE are known to work with pyftpdlib and every new version is usually tested against it. pyftpdlib currently does not work on Jython since the latest Jython release refers to CPython 2.2.x serie. The best way to know whether pyftpdlib works on your platform is installing it and running its test suite. Usage¶How can I run long-running tasks without blocking the server?¶pyftpdlib is an asynchronous FTP server. That means that if you need to run a time consuming task you have to use a separate Python process or thread for the actual processing work otherwise the entire asynchronous loop will be blocked. Let's suppose you want to implement a long-running task every time the server receives a file. The code snippet below shows the correct way to do it by using a thread. Notice how we first set FTPHandler.sleeping attribute to True, then we set it back to False when the long-running task has completed. class MyHandler(ftpserver.FTPHandler):
def on_file_received(self, file):
"""Called every time a file has been received"""
def blocking_task():
time.sleep(5)
self.sleeping = False
self.sleeping = True
threading.Thread(target=blocking_task).start()Why do I get socket.error "Permission denied" error on ftpd starting?¶Probably because you're on a Unix system and you're trying to start ftpd as an unprivileged user. ftpserver.py binds on port 21 by default and only super-user account (e.g. root) can bind sockets on such ports. If you want to bind ftpd as non-privileged user you should set a port higher than 1024. How can I prevent the server version from being displayed?¶Just modify banner attribute of FTPHandler class. Can control upload/download ratios?¶Yes. Starting from version 0.5.2 ftpserver.py provides a new class called ThrottledDTPHandler. You can set speed limits by modifying read_limit and write_limit class attributes as it is shown in throttled_ftpd.py demo script. Are there ways to limit connections?¶FTPServer class comes with two overridable attributes defaulting to zero (no limit): max_cons, which sets a limit for maximum simultaneous connection to handle by ftpd and max_cons_per_ip which set a limit for connections from the same IP address. Overriding these variables is always recommended to avoid DoS attacks. I'm behind a NAT / gateway¶When behind a NAT a ftp server needs to replace the IP local address displayed in PASV replies and instead use the public address of the NAT to allow client to connect. By overriding masquerade_address attribute of FTPHandler class you will force pyftpdlib to do such replacement. However, one problem still exists. The passive FTP connections will use ports from 1024 and up, which means that you must forward all ports 1024-65535 from the NAT to the FTP server! And you have to allow many (possibly) dangerous ports in your firewalling rules! To resolve this, simply override passive_ports attribute of FTPHandler class to control what ports pyftpdlib will use for its passive data transfers. Value expected by passive_ports attribute is a list of integers (e.g. range(60000, 65535)) indicating which ports will be used for initializing the passive data channel. In case you run a FTP server with multiple private IP addresses behind a NAT firewall with multiple public IP addresses you can use FTPHandler.masquerade_address_map option which allows you to define multiple 1 to 1 mappings (New in 0.6.0). What is FXP?¶FXP is part of the name of a popular Windows FTP client: http://www.flashfxp.com. This client has made the name "FXP" commonly used as a synonym for site-to-site FTP transfers, for transferring a file between two remote FTP servers without the transfer going through the client's host. Sometimes "FXP" is referred to as a protocol; in fact, it is not. The site-to-site transfer capability was deliberately designed into RFC-959. More info can be found here: http://www.proftpd.org/docs/howto/FXP.html. Does pyftpdlib support FXP?¶Yes. It is disabled by default for security reasons (see RFC-2257 and FTP bounce attack description) but in case you want to enable it just set to True the permit_foreign_addresses attribute of FTPHandler class. Why timestamps shown by MDTM and ls commands (LIST, MLSD, MLST) are wrong?¶If by "wrong" you mean "different from the timestamp of that file on my client machine", then that is the expected behavior. Starting from version 0.6.0 pyftpdlib uses GMT times as recommended in RFC-3659. In case you want such commands to report local times instead just set the FTPHandler.use_gmt_times attribute to False. For further information you might want to take a look at this Proftpd FAQ. Implementation¶Globbing / STAT command implementation¶Globbing is a common Unix shell mechanism for expanding wildcard patterns to match multiple filenames. When an argument is provided to the STAT command, ftpd should return directory listing over the command channel. RFC-959 does not explicitly mention globbing; this means that FTP servers are not required to support globbing in order to be compliant. However, many FTP servers do support globbing as a measure of convenience for FTP clients and users. In order to search for and match the given globbing expression, the code has to search (possibly) many directories, examine each contained filename, and build a list of matching files in memory. Since this operation can be quite intensive, both CPU- and memory-wise, pyftpdlib does not support globbing. ASCII transfers / SIZE command implementation¶Properly handling the SIZE command when TYPE ASCII is used would require to scan the entire file to perform the ASCII translation logic (file.read().replace(os.linesep, '\r\n')) and then calculating the len of such data which may be different than the actual size of the file on the server. Considering that calculating such result could be very resource-intensive it could be easy for a malicious client to try a DoS attack, thus pyftpdlib rejects SIZE when the current TYPE is ASCII. However, clients in general should not be resuming downloads in ASCII mode. Resuming downloads in binary mode is the recommended way as specified in RFC-3659. IPv6 support¶Starting from version 0.4.0 pyftpdlib supports IPv6 (RFC-2428). If you use IPv6 and want your FTP daemon to do so just pass a valid IPv6 address to the FTPServer class constructor. Example: >>> from pyftpdlib import ftpserver
>>> address = ("::1", 21) # listen on localhost, port 21
>>> ftpd = ftpserver.FTPServer(address, ftpserver.FTPHandler)
>>> ftpd.serve_forever()
Serving FTP on ::1:21If your OS (for example: all recent UNIX systems) have an hybrid dual-stack IPv6/IPv4 implementation the code above will listen on both IPv4 and IPv6 by using a single IPv6 socket (New in 0.6.0). How do I install IPv6 support on my system?¶If you want to install IPv6 support on Linux run "modprobe ipv6", then "ifconfig". This should display the loopback adapter, with the address "::1". You should then be able to listen the server on that address, and connect to it. On Windows (XP SP2 and higher) run "netsh int ipv6 install". Again, you should be able to use IPv6 loopback afterwards. Can pyftpdlib be integrated with "real" users existing on the system?¶Yes. Starting from version 0.6.0 pyftpdlib provides the new UnixAuthorizer and WindowsAuthorizer classes. By using them pyftpdlib can look into the system account database to authenticate users. They also assume the id of real users every time the FTP server is going to access the filesystem (e.g. for creating or renaming a file) the authorizer will temporarily impersonate the currently logged on user, execute the filesystem call and then switch back to the user who originally started the server. Example UNIX and Windows FTP servers contained in the demo directory shows how to use UnixAuthorizer and WindowsAuthorizer classes. Does pyftpdlib support FTP over TLS/SSL (FTPS)¶Yes, starting from version 0.6.0, see: http://code.google.com/p/billiejoex/wiki/Tutorial#3.7_-_FTPS_(FTP_over_TLS/SSL)_server What about SITE commands?¶No SITE commands aside from SITE HELP are implemented by default. The user willing to add support for a specific SITE command (e.g. SITE CHMOD) has to define a new ftp_SITE_%CMD% method in the FTPHandler subclass and add a new entry in ftpserver.proto_cmds dictionary. Example: from pyftpdlib import ftpserver
prop = (None, True, None, False, 'Syntax: SITE CHMOD <SP> path (change file permission).')
ftpserver.proto_cmds['SITE CHMOD'] = ftpserver._CommandProperty(*prop)
class CustomizedFTPHandler(ftpserver.FTPHandler):
def ftp_SITE_CHMOD(self, line):
"""Change file permissions."""
...
|