Expose an FS object over SFTP (via paramiko).

This module provides the necessary interfaces to expose an FS object over SFTP, plugging into the infrastructure provided by the ‘paramiko’ module.

For simple usage, the class ‘BaseSFTPServer’ provides an all-in-one server class based on the standard SocketServer module. Use it like so:

server = BaseSFTPServer((hostname,port),fs)

Note that the base class allows UNAUTHENTICATED ACCESS by default. For more serious work you will probably want to subclass it and override methods such as check_auth_password() and get_allowed_auths().

To integrate this module into an existing server framework based on paramiko, the ‘SFTPServerInterface’ class provides a concrete implementation of the paramiko.SFTPServerInterface protocol. If you don’t understand what this is, you probably don’t want to use it.

class fs.expose.sftp.BaseSFTPServer(address, fs=None, encoding=None, host_key=None, RequestHandlerClass=None)

SocketServer.TCPServer subclass exposing an FS via SFTP.

Operation is in the standard SocketServer style. The target FS object can be passed into the constructor, or set as an attribute on the server:

server = BaseSFTPServer((hostname,port),fs)

It is also possible to specify the host key used by the sever by setting the ‘host_key’ attribute. If this is not specified, it will default to the key found in the DEFAULT_HOST_KEY variable.

class fs.expose.sftp.BaseServerInterface

Paramiko ServerInterface implementation that performs user authentication.

Note that this base class allows UNAUTHENTICATED ACCESS to the exposed FS. This is intentional, since we can’t guess what your authentication needs are. To protect the exposed FS, override the following methods:

  • get_allowed_auths Determine the allowed auth modes
  • check_auth_none Check auth with no credentials
  • check_auth_password Check auth with a password
  • check_auth_publickey Check auth with a public key

Check whether the user can proceed without authentication.

check_auth_password(username, password)

Check whether the given password is valid for authentication.

check_auth_publickey(username, key)

Check whether the given public key is valid for authentication.


Return string containing a comma separated list of allowed auth modes.

The available modes are “node”, “password” and “publickey”.

class fs.expose.sftp.SFTPHandle(owner, path, flags)

SFTP file handler pointing to a file in an FS object.

This is a simple file wrapper for SFTPServerInterface, passing read and write requests directly through the to underlying file from the FS.

class fs.expose.sftp.SFTPRequestHandler(request, client_address, server)

SocketServer RequestHandler subclass for BaseSFTPServer.

This RequestHandler subclass creates a paramiko Transport, sets up the sftp subsystem, and hands off to the transport’s own request handling thread.


Start the paramiko server, this will start a thread to handle the connection.


Creates the SSH transport. Sets security options.

class fs.expose.sftp.SFTPServer(channel, name, server, sftp_si=<class 'paramiko.sftp_si.SFTPServerInterface'>, *largs, **kwargs)

An SFTPServer class that closes the filesystem when done.

The constructor for SFTPServer is meant to be called from within the .Transport as a subsystem handler. server and any additional parameters or keyword parameters are passed from the original call to .Transport.set_subsystem_handler.

  • channel (Channel) – channel passed from the .Transport.
  • name (str) – name of the requested subsystem.
  • server (ServerInterface) – the server object associated with this channel and subsystem
  • sftp_si (class) – a subclass of .SFTPServerInterface to use for handling individual requests.
class fs.expose.sftp.SFTPServerInterface(server, fs, encoding=None, *args, **kwds)

SFTPServerInterface implementation that exposes an FS object.

This SFTPServerInterface subclass expects a single additional argument, the fs object to be exposed. Use it to set up a transport subsystem handler like so:


If this all looks too complicated, you might consider the BaseSFTPServer class also provided by this module - it automatically creates the enclosing paramiko server infrastructure.


Decorator to catch and report FS errors as SFTP error codes.

Any FSError exceptions are caught and translated into an appropriate return code, while other exceptions are passed through untouched.