API reference
pyftpdlib implements the server side of the FTP protocol as defined in RFC-959. This document is intended to serve as a simple API reference of most important classes and functions. Also see the tutorial document.
Modules and classes hierarchy
pyftpdlib.authorizers.AuthenticationFailed
pyftpdlib.authorizers.DummyAuthorizer
pyftpdlib.authorizers.UnixAuthorizer
pyftpdlib.authorizers.WindowsAuthorizer
pyftpdlib.handlers.FTPHandler
pyftpdlib.handlers.TLS_FTPHandler
pyftpdlib.handlers.DTPHandler
pyftpdlib.handlers.TLS_DTPHandler
pyftpdlib.handlers.ThrottledDTPHandler
pyftpdlib.filesystems.FilesystemError
pyftpdlib.filesystems.AbstractedFS
pyftpdlib.filesystems.UnixFilesystem
pyftpdlib.servers.FTPServer
pyftpdlib.servers.ThreadedFTPServer
pyftpdlib.servers.MultiprocessFTPServer
pyftpdlib.ioloop.IOLoop
pyftpdlib.ioloop.Connector
pyftpdlib.ioloop.Acceptor
pyftpdlib.ioloop.AsyncChat
Users
- class pyftpdlib.authorizers.DummyAuthorizer
Basic “dummy” authorizer class which lets you create virtual users. It is also suitable for subclassing to create your own custom authorizer. The “authorizer” is a class handling authentications and permissions of the FTP server. It is used by
pyftpdlib.handlers.FTPHandler
class for verifying user passwords, getting users home directory and checking user permissions when a filesystem event occurs. Example usage:>>> from pyftpdlib.authorizers import DummyAuthorizer >>> authorizer = DummyAuthorizer() >>> authorizer.add_user('user', 'password', '/home/user', perm='elradfmwMT') >>> authorizer.add_anonymous('/home/nobody')
- add_user(username, password, homedir, perm='elr', msg_login='Login successful.', msg_quit='Goodbye.')
Add a user to the virtual users table.
AuthorizerError
exception is raised on error conditions such as insufficient permissions or duplicate usernames. The perm argument is a set of letters indicating the user’s permissions:Read permissions:
"e"
= change directory (CWD, CDUP commands)"l"
= list files (LIST, NLST, STAT, MLSD, MLST, SIZE commands)"r"
= retrieve file from the server (RETR command)
Write permissions:
"a"
= append data to an existing file (APPE command)"d"
= delete file or directory (DELE, RMD commands)"f"
= rename file or directory (RNFR, RNTO commands)"m"
= create directory (MKD command)"w"
= store a file to the server (STOR, STOU commands)"M"
= change file mode / permission (SITE CHMOD command) New in 0.7.0"T"
= change file modification time (SITE MFMT command) New in 1.5.3
msg_login and msg_quit arguments can be specified to provide customized response strings when the user logs in and quits.
- add_anonymous(homedir, **kwargs)
Add an anonymous user to the virtual users table. The keyword arguments are the same expected by
add_user()
method. The only difference is that if write permissions are passed as perm aRuntimeWarning
will be raised.
- override_perm(username, directory, perm, recursive=False)
Override user permissions for a specific directory.
- validate_authentication(username, password, handler)
Raises
pyftpdlib.authorizers.AuthenticationFailed
if the supplied username and password don’t match the stored credentials.Changed in 1.0.0: new handler parameter.
Changed in 1.0.0: an exception is now raised for signaling a failed authenticaiton as opposed to returning a bool.
- impersonate_user(username, password)
Impersonate another user (noop). It is always called before accessing the filesystem. By default it does nothing. The subclass overriding this method may provide a mechanism to change the current user.
- terminate_impersonation(username)
Terminate impersonation (noop). It is always called after having accessed the filesystem. By default it does nothing. The subclass overriding this method may provide a mechanism to switch back to the original user.
- remove_user(username)
Remove a user from the virtual user table.
Control connection
- class pyftpdlib.handlers.FTPHandler(conn, server)
This class implements the “FTP server Protocol Interpreter” as defined in RFC-959, commonly known as the FTP “control connection”. It handles the commands received from the client. E.g. if command “MKD pathname” is received,
ftp_MKD()
method is called withpathname
as the argument.conn
argument is a socket object instance of the newly established connection.server
is a reference to thepyftpdlib.servers.FTPServer
class instance. Basic usage requires creating an instance of this class and specify which authorizer it is going to use:>>> from pyftpdlib.handlers import FTPHandler >>> handler = FTPHandler >>> handler.authorizer = authorizer
Configurable class attributes:
- timeout
The timeout which is the maximum time a remote client may spend between FTP commands. If the timeout triggers, the remote client will be kicked off. Default:
300
seconds.New in version 5.0
- banner
The string sent when client connects. The default is
"pyftpdlib %s ready." %__ver__
. If you want to make this dynamic you can define this as a property.
- max_login_attempts
Maximum number of wrong authentications before disconnecting (default
3
).
- permit_foreign_addresses
Also known as “FXP” or “site-to-site transfer feature”. If
True
it allows for transferring a file between two remote FTP servers, without the transfer going through the client’s host. This is not recommended for security reasons as described in RFC-2577. Having this attribute set toFalse
means that all data connections from/to remote IP addresses which do not match the client’s IP address will be dropped. Default:False
.
- permit_privileged_ports
Set to
True
if you want to permit active connections (PORT) over privileged ports. Not recommended for security reason. Default:False
.
- masquerade_address
The “masqueraded” IP address to provide along PASV reply when pyftpdlib is running behind a NAT or other types of gateways. When configured pyftpdlib will hide its local address and instead use the public address of your NAT. Use this if you’re behing a NAT. Default:
None
.
- masquerade_address_map
In case the server has multiple IP addresses which are all behind a NAT, you may wish to specify individual masquerade addresses for each of them. The map expects a dictionary containing private IP addresses as keys, and their corresponding public (masquerade) addresses as values. Default:
{}
(empty dict).New in version 0.6.0
- passive_ports
What TCP ports the FTP server will use for passive (PASV) data transfers. The value expected is a list of integers (e.g.
list(range(60000, 65535))
). When configured, pyftpdlib will no longer use kernel-assigned random TCP ports. Default:None
.
- use_gmt_times
When
True
causes the FTP server to report all times as GMT. This affects MDTM, MFMT, LIST, MLSD and MLST commands. If set toFalse
, the times will be expressed in the server local time (not recommended). Default:True
.New in version 0.6.0
- tcp_no_delay
Controls the use of the TCP_NODELAY socket option, which disables the Nagle algorithm. It usually result in significantly better performances. Default
True
on all platforms where it is supported.New in version 0.6.0
- use_sendfile
When
True
uses thesendfile(2)
system call when sending file, resulting in considerable faster uploads (from server to client). Works on Linux only, and only for clear-text (non FTPS) transfers. Default:True
on Linux.New in version 0.7.0
- encoding
The encoding used for client / server communication. Defaults to
'utf-8'
.New in version 2.0.0
- auth_failed_timeout
The amount of time the server waits before sending a response in case of failed authentication. This is useful to prevent password-guessing attacks. Default:
3
seconds.New in version 1.5.0
Follows a list of callback methods that can be overridden in a subclass. For blocking operations read the FAQ on how to run time consuming tasks.
- on_connect()
Called when client connects.
New in version 1.0.0
- on_disconnect()
Called when connection is closed.
New in version 1.0.0
- on_login(username)
Called on user login.
New in version 0.6.0
- on_login_failed(username, password)
Called on failed user login.
New in version 0.7.0
- on_logout(username)
Called when user logs out due to QUIT or USER commands issued twice. This is not called if the client just disconnects without issuing QUIT first.
New in version 0.6.0
- on_file_sent(file)
Called when a file has been successfully sent.
file
is the absolute path of that file.
- on_file_received(file)
Called when a file has been successfully received.
file
is the absolute path of that file.
- on_incomplete_file_sent(file)
Called when time a file has not been entirely sent (e.g. transfer aborted by client).
file
is the absolute path of that file.New in version 0.6.0
- on_incomplete_file_received(file)
Called when a file has not been entirely received (e.g. transfer aborted by client). file is the absolute path of that file.
New in version 0.6.0
Data connection
- class pyftpdlib.handlers.DTPHandler(sock_obj, cmd_channel)
This class handles the server-data-transfer-process (server-DTP) as defined in RFC-959, commonly known as “data connection”. It manages all the transfer operations like sending or receiving files and also transmitting the directory listing.
sock_obj
is the underlying socket object instance of the newly established connection,cmd_channel
is the correspondingpyftpdlib.handlers.FTPHandler
class instance.Changed in version 1.0.0: added ioloop argument.
- timeout
The timeout which roughly is the maximum time we permit data transfers to stall for with no progress. If the timeout triggers, the remote client will be kicked off. Default:
300
seconds.
- ac_in_buffer_size
- ac_out_buffer_size
The buffer sizes to use when receiving and sending data (both defaulting to
65536
bytes). For LANs you may want this to be fairly large. Depending on available memory and number of connected clients, setting them to a lower value can result in better performances.
- class pyftpdlib.handlers.ThrottledDTPHandler(sock_obj, cmd_channel)
A
pyftpdlib.handlers.DTPHandler
subclass which wraps sending and receiving in a data counter, and temporarily “sleeps” the transmission of data so that you burst to no more than x Kb/sec average. Use it instead ofpyftpdlib.handlers.DTPHandler
to set transfer rates limits for both downloads and/or uploads (see the demo script showing the example usage).- read_limit
The maximum number of bytes to read (receive) in one second. Defaults to
0
, meaning no limit.
- write_limit
The maximum number of bytes to write (send) in one second. Defaults to
0
, meaning no limit.
Server (acceptor)
- class pyftpdlib.servers.FTPServer(address_or_socket, handler, ioloop=None, backlog=100)
Creates a socket listening on
address
(an(host, port)
tuple) or a pre-existing socket object, dispatching the requests tohandler
(typically apyftpdlib.handlers.FTPHandler
class). Also, it starts the main asynchronous IO loop.backlog
is the maximum number of queued connections passed to socket.listen().Changed in version 1.0.0: added ioloop argument.
Changed in version 1.2.0: address can also be a pre-existing socket object.
Changed in version 1.2.0: Added backlog argument.
Changed in version 1.5.4: Support for the context manager protocol was added. Exiting the context manager is equivalent to calling :meth:`close_all`.
>>> from pyftpdlib.servers import FTPServer >>> address = ('127.0.0.1', 21) >>> server = FTPServer(address, handler) >>> server.serve_forever()
FTPServer
can also be used as a context manager. Exiting the context manager is equivalent to callingclose_all()
.>>> with FTPServer(address, handler) as server: ... server.serve_forever()
- max_cons
The number of maximum simultaneous connections accepted by the server (both control and data connections). Default:
512
.
- max_cons_per_ip
Then number of maximum connections accepted for the same IP address. Default:
0
, meaning no limit.
- serve_forever(timeout=None, blocking=True, handle_exit=True, worker_processes=1)
Starts the asynchronous IO loop.
timeout
: the timeout passed to the underlying IO loop expressed in seconds.blocking
: ifFalse
loop once and then return the timeout of the next scheduled call next to expire soonest (if any).handle_exit
: whenTrue
catchesKeyboardInterrupt
andSystemExit
exceptions (caused by SIGTERM / SIGINT signals) and gracefully exits after cleaning up resources. Also, logs server start and stop.worker_processes
: pre-forks a certain number of child processes before starting. See: Pre fork model for more info. Each child process will keep using a 1-thread, async concurrency model, handling multiple concurrent connections. If the number isNone
or <=0
, the number of usable CPUs available on this machine is detected and used. It is a good idea to use this option in case the server risks blocking for too long on a single function call, typically if the filesystem is slow or the are long DB query executed on user login. By splitting the work load over multiple processes the delay introduced by a blocking function call is amortized and divided by the number of the worker processes.
Changed in version 1.0.0: no longer a classmethod
Changed in version 1.0.0:
use_poll
andcount
parameters were removedChanged in version 1.0.0:
blocking
andhandle_exit
parameters were added
- close()
Stop accepting connections without disconnecting the clients currently connected.
server_forever()
loop will automatically stop when the last client disconnects.
- close_all()
Disconnect all clients, tell
server_forever()
loop to stop and wait until it does.Changed in version 1.0.0: ``map`` and ``ignore_all`` parameters were removed.
Filesystem
- class pyftpdlib.filesystems.FilesystemError
Exception class which can be raised from within
pyftpdlib.filesystems.AbstractedFS
in order to send a custom error messages to the client.New in version 1.0.0
- class pyftpdlib.filesystems.AbstractedFS(root, cmd_channel)
A class used to interact with the filesystem, providing a cross-platform interface compatible with both Windows and UNIX paths. All paths use
"/"
as the separator, including on Windows.AbstractedFS
distinguishes between “real” filesystem paths and “virtual” FTP paths, emulating a UNIX chroot jail where the user can not escape his/her home directory (example: real “/home/user” path will be seen as “/” by the client). It also provides wrappers around allos.*
calls (mkdir
,rename
, etc) andopen
builtin. The contructor accepts two arguments which are passed by theFTPHandler
:root
, which is the user “real” home directory (e.g. ‘/home/user’) andcmd_channel
which is apyftpdlib.handlers.FTPHandler
class instance.Changed in version 0.6.0: root and cmd_channel arguments were added.
- root
User’s home directory (“real”).
Changed in version 0.7.0: support setattr()
- cwd
User’s current working directory (“virtual”).
Changed in version 0.7.0: support setattr()
- ftpnorm(ftppath)
Normalize a “virtual” FTP pathname depending on the current working directory. E.g. having
"/foo"
as current working directory,"bar"
is translated to"/foo/bar"
.
- ftp2fs(ftppath)
Translate a “virtual” FTP pathname into the equivalent absolute “real” filesystem pathname. E.g. having
"/home/user"
as the root directory,"foo"
is translated to"/home/user/foo"
.
- fs2ftp(fspath)
Translate a “real” filesystem pathname into equivalent absolute “virtual” FTP pathname depending on the user’s root directory. E.g. having
"/home/user"
as root directory,"/home/user/foo"
is translated to"/foo"
.
- validpath(path)
- Check whether the path belongs to the user's home directory. Expected
- argument is a "real" filesystem path. If path is a symbolic link it is
- resolved to check its real destination. Resolved symlinks which escape the
- user's root directory are considered not valid (return ``False``).
- mkdir(path)
- chdir(path)
- rmdir(path)
- remove(path)
- rename(src, dst)
- chmod(path, mode)
- stat(path)
- lstat(path)
- isfile(path)
- islink(path)
- isdir(path)
- getsize(path)
- getmtime(path)
- realpath(path)
- mkstemp(suffix='', prefix='', dir=None, mode='wb')
Wrapper around tempfile.mkstemp.
- listdir(path)
Wrapper around os.listdir. It is expected to return a list of strings or a generator yielding strings.
Changed in version 1.6.0: can also return a generator.
Extended classes
Classes that require third-party modules to be installed separately, or a specific to a given operating system.
Extended handlers
- class pyftpdlib.handlers.TLS_FTPHandler(conn, server)
A
pyftpdlib.handlers.FTPHandler
subclass implementing FTPS (FTP over SSL/TLS) as described in RFC-4217. Implements AUTH, PBSZ and PROT commands. PyOpenSSL module is required to be installed. See FTPS (FTP over TLS/SSL) server tutorial. Configurable attributes:- certfile
The path to a file which contains a certificate to be used to identify the local side of the connection. This must always be specified, unless a :ref`:ssl_context is provided instead. See FTPS (FTP over TLS/SSL) server on how to generate SSL certificates. Default:
None
.
- keyfile
The path of the file containing the private RSA key. It can be omittetted if the :ref`:certfile already contains the private key. See FTPS (FTP over TLS/SSL) server on how to generate SSL certificates. Default:
None
.
- ssl_protocol
The desired SSL protocol version to use. This defaults to
TLS_SERVER_METHOD
, which at the time of writing (year 2024) includes TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. The actual protocol version used will be negotiated to the highest version mutually supported by the client and the server when the client connects.Changed in version 2.0.0: set default to
TLS_SERVER_METHOD
- ssl_options
Specific OpenSSL options. This defaults to:
OP_NO_SSLv2 | OP_NO_SSLv3 | OP_NO_COMPRESSION
, which are all considered unsecure settings. It can be set toNone
in order to improve compatibilty with older (insecure) FTP clients (not recommended).Added in version 1.6.0.
- ssl_context
A SSL.Context instance which was previously configured. When specified,
ssl_protocol
andssl_options
parameters are ignored.
- tls_control_required
If
True
it requires the client to secure the control connection with TLS before logging in. This means the client will have to issue the AUTH command before USER and PASS. Default:False
.
- tls_data_required
If
True
it requires the client to secure the data connection with TLS before logging in. This means the clie will have to issue the PROT command before PASV or PORT. Default:False
.
Extended filesystems
- class pyftpdlib.filesystems.UnixFilesystem(root, cmd_channel)
Represents the real UNIX filesystem. Differently from
pyftpdlib.filesystems.AbstractedFS
the client will login into /home/<username> and will be able to escape its home directory and navigate the real filesystem. Use it in conjuction withpyftpdlib.authorizers.UnixAuthorizer
to implement a “real” UNIX FTP server (see demo/unix_ftpd.py).New in version 0.6.0
Extended servers
- class pyftpdlib.servers.ThreadedFTPServer(address_or_socket, handler, ioloop=None, backlog=5)
A modified version of base
pyftpdlib.servers.FTPServer
class which spawns a thread every time a new connection is established. Differently from base FTPServer class, the handler will be free to block without hanging the whole IO loop. See Changing the concurrency model.New in version 1.0.0
Changed in 1.2.0: added ioloop parameter; address can also be a pre-existing *socket.
- class pyftpdlib.servers.MultiprocessFTPServer(address_or_socket, handler, ioloop=None, backlog=5)
A modified version of base
pyftpdlib.servers.FTPServer
class which spawns a process every time a new connection is established. Differently from base FTPServer class, the handler will be free to block without hanging the whole IO loop. See Changing the concurrency model.New in version 1.0.0
Changed in 1.2.0: added ioloop parameter; address can also be a pre-existing socket.
Availability: POSIX