sftpserver (rspivak)

Common errors

• sftpserver: error: -k/--keyfile should be specified

  cause The server was started without providing a path to a private SSH key file.
  fix Run the server with the `-k` or `--keyfile` option followed by the path to a private key, e.g., `sftpserver -k my_server_key.key` or `sftpserver.start_server(..., keyfile='/path/to/key')`.

• The authenticity of host '[localhost]:3373' can't be established. RSA key fingerprint is ... Are you sure you want to continue connecting (yes/no)?

  cause This is a standard SSH client prompt when connecting to a server for the first time, or if the server's host key has changed.
  fix For a trusted local test server, type `yes` and press Enter. For automated testing, configure the client to automatically add host keys or disable strict host key checking (e.g., `ssh -o StrictHostKeyChecking=no ...` or `client.set_missing_host_key_policy(paramiko.AutoAddPolicy())`).

• paramiko.ssh_exception.SSHException: No authentication methods available

  cause The client attempted to connect but no valid credentials (username/password or key) were provided or accepted by the server. The default `sftpserver` accepts any credentials, so this usually indicates a client-side misconfiguration.
  fix Ensure your client provides a username and password (e.g., 'admin'/'admin') or a private key that matches the server's configuration. Verify the client's `paramiko.Transport.connect()` call includes correct `username` and `password` or `pkey` arguments.

• ssh_exchange_identification: Connection closed by remote host

  cause The SFTP server process either crashed, was not running, or immediately rejected the connection attempt at a very early stage (e.g., due to port or firewall issues).
  fix Verify the `sftpserver` process is running. Check for any errors in the server's console output. Ensure no firewall is blocking the specified port (default 3373) on the server machine. Double-check the host and port in your client configuration.

Warnings

• breaking The library is explicitly stated as 'simple single-threaded' and 'not for production use'. Relying on it for high-traffic or critical production environments will lead to performance bottlenecks and instability.
  Fix: For production, consider robust SFTP server solutions (e.g., OpenSSH, commercial products) or actively maintained Python libraries like `asyncssh` or `pysftpserver` which offer more features and better concurrency.
• gotcha The server requires a private key file (`-k/--keyfile`) to operate, which must be specified either via command-line arguments or when calling `start_server`. Failure to provide one will result in an error.
  Fix: Generate an RSA private key using `openssl req -newkey rsa:2048 -nodes -keyout /tmp/test_rsa.key -x509 -days 365 -out /tmp/test_rsa.key.pub` or `paramiko.RSAKey.generate(2048).write_private_key_file(key_path)` and provide its path to the server.
• deprecated Given the last update in 2017, `sftpserver` likely uses older versions of `paramiko` and may support only outdated SSH/SFTP ciphers and algorithms, which are considered insecure by modern standards.
  Fix: Avoid using this library for sensitive data. If used for testing, ensure the client explicitly allows older, weaker ciphers/algorithms if connection issues arise, or configure your client to disable strict host key checking for local testing (e.g., `StrictHostKeyChecking no` for `sftp` clients) for ephemeral test servers.

Install

• pip install sftpserver Install latest version

Imports

• start_server

  import sftpserver
  sftpserver.start_server(...)

  The library is designed for direct execution or calling the start_server function from the main module.

Quickstart

This quickstart demonstrates how to start the sftpserver programmatically, generating a temporary RSA key if one doesn't exist. It will listen on 127.0.0.1:3373 by default. Connect with a client using any username/password (e.g., 'admin'/'admin') as the default handler accepts all credentials.

import os
import paramiko
import sftpserver

# Generate a test private key if it doesn't exist
key_file = 'test_rsa.key'
if not os.path.exists(key_file):
    print(f"Generating new RSA key for the server: {key_file}")
    key = paramiko.RSAKey.generate(2048)
    key.write_private_key_file(key_file)
    print("Key generated. DO NOT use this key for production.")

# Define SFTP server parameters
SFTP_HOST = os.environ.get('SFTP_HOST', '127.0.0.1')
SFTP_PORT = int(os.environ.get('SFTP_PORT', '3373'))
SFTP_KEY_FILE = os.environ.get('SFTP_KEY_FILE', key_file)
SFTP_LOG_LEVEL = os.environ.get('SFTP_LOG_LEVEL', 'INFO')

print(f"Starting SFTP server on {SFTP_HOST}:{SFTP_PORT}")
print(f"Using key file: {SFTP_KEY_FILE}")
print(f"Log level: {SFTP_LOG_LEVEL}")
print("Connect with username 'admin', password 'admin' (or any credential if no auth callback is set).")
print("Press Ctrl+C to stop the server.")

try:
    sftpserver.start_server(SFTP_HOST, SFTP_PORT, SFTP_KEY_FILE, SFTP_LOG_LEVEL)
except KeyboardInterrupt:
    print("\nSFTP server stopped.")