Standard library · Network

sftpd

An SFTP server for file transfer over SSH with password login and a root directory.

import sftpd

This package is an SFTP server written in Salam: a server that does one thing, file transfer over SSH. It is built on the sshd package, so it logs users in the same way and uses the same host key, but it allows only the SFTP subsystem. A client cannot run a command or open a shell, which is what you want for a drop box where partners upload and download files you trust them with.

Give it a root directory and a list of users, call Listen and then Serve. Clients are the usual ones: sftp from OpenSSH, FileZilla, or the ssh package with SftpOpen, Upload and Download.

What to know before you use it:

  • Users are the User values of the sshd package, with a name, a password and a home directory below the root. Login is by password.
  • Set host_key_file to the path of an OpenSSH private key. Without it the server uses a key that is built into the library and that everyone can read, which is only fine for tests.
  • The root is where paths start, not a security boundary. Clients see root as /, but a user can create a symbolic link through SFTP that points outside it, so give accounts only to people you would trust with every file the server process can write.
  • Connections are served one after another, so a long transfer holds up the next client.

Defaults and a free port

A fresh configuration listens on all interfaces on port 22 and serves the current directory. The program below fills in a user, binds to port 0 on the loopback address, and reads the port the system chose with Port. Nothing connects, so it runs without a network.

sftpd-listen.salam
import sftpd
import sshd

func main:
    mut cfg := sftpd.NewConfig()
    println cfg.port, cfg.root
    cfg.host = "127.0.0.1"
    cfg.port = 0
    cfg.root = "/srv/drop"
    cfg.users.push(sshd.User { name = "partner", password = "s3cret", home = "/" })
    println cfg.users.len()
    mut srv := sftpd.New(cfg)
    println sftpd.Listen(srv)
    println sftpd.Port(srv) > 0
    sftpd.Close(srv)
    println srv.running
end
Output22 . 1 true true false

Run a drop box

For a real server set the root, the host key and the users, then check Listen before Serve. Ports below 1024, including 22, need extra rights on most systems, so the example uses 2222. The password is read from SFTP_PASSWORD, so none is written in the page.

sftpd-serve.salam
import sftpd
import sshd
import env

func main:
    mut cfg := sftpd.NewConfig()
    cfg.port = 2222
    cfg.root = "/srv/drop"
    cfg.host_key_file = "/etc/deploy/host_key"
    cfg.users.push(sshd.User { name = "partner", password = env.Get("SFTP_PASSWORD"), home = "/" })
    if env.Get("SFTP_PASSWORD").len() == 0:
        println "set SFTP_PASSWORD first"
        ret 1
    end
    mut srv := sftpd.New(cfg)
    if not sftpd.Listen(srv):
        println "cannot listen on port", cfg.port
        ret 1
    end
    println "sftp server on port", sftpd.Port(srv)
    sftpd.Serve(srv)
    ret 0
end

This runs until it is stopped, so it is only checked here. Connect with sftp -P 2222 partner@host.

Which function for which job

JobUse
Start from the defaultsNewConfig, then set the fields of Config
Create the serverNew
Open the portListen, then Port to read it
Serve clients until stoppedServe
Serve exactly one connectionServeOnce
Stop and free the portClose

Types

Config

struct Config
The configuration of an SFTP server.
NameTypeDescription
hoststr = "0.0.0.0"The address to listen on; 0.0.0.0 means every interface.
portint = 22The port to listen on; 22 by default, and 0 lets the system choose one.
rootstr = "."The directory the clients see as /; nothing above it can be reached.
host_key_filestr = ""The path of the OpenSSH private key that is the identity of the server.
usersVectorThe users who may log in, as sshd.User values.
sftpd-Config.salam
import sftpd
import sshd

func main:
    mut cfg := sftpd.NewConfig()
    println cfg.host, cfg.port, cfg.root
    println cfg.host_key_file == "", cfg.users.len()
    cfg.root = "/srv/drop"
    cfg.users.push(sshd.User { name = "partner", password = "s3cret", home = "/" })
    println cfg.root, cfg.users.len(), cfg.users.get(0).name
end
Output0.0.0.0 22 . true 0 /srv/drop 1 partner

Server

struct Server
A running SFTP server.
NameTypeDescription
configConfigThe configuration the server was made with; after Listen its port is the real one.
ssh_serversshd.ServerThe SSH server underneath, set up to allow SFTP only.
runningbool = falseTrue after Listen worked and until Close is called.
sftpd-Server.salam
import sftpd

func main:
    mut cfg := sftpd.NewConfig()
    cfg.host = "127.0.0.1"
    cfg.port = 0
    mut srv := sftpd.New(cfg)
    println srv.running
    println sftpd.Listen(srv), srv.running
    println sftpd.Port(srv) > 0
    sftpd.Close(srv)
    println srv.running
end
Outputfalse true true true false

Functions

NewConfig

func NewConfig(): Config
A configuration with the defaults: port 22, the current directory as root, no users.

The example for this item is shown with the ones above: sftpd-Config.salam

New

func New(cfg: Config): Server
Makes a server from a configuration, with commands and the shell switched off. It does not listen yet.

The example for this item is shown with the ones above: sftpd-Server.salam

Listen

func Listen(srv &: Server): bool
Opens the port; false when it could not be bound.

The example for this item is shown with the ones above: sftpd-Server.salam

Close

func Close(srv &: Server)
Stops the server and frees the port.

The example for this item is shown with the ones above: sftpd-Server.salam

Port

func Port(srv: Server): int
The port the server listens on; the real one after Listen when the configuration said 0.

The example for this item is shown with the ones above: sftpd-Server.salam

ServeOnce

func ServeOnce(srv &: Server): bool
Waits for one connection and serves it until the client leaves; false when the server is not listening or the accept failed.
sftpd-Serve.salam
import sftpd

func main:
    mut cfg := sftpd.NewConfig()
    cfg.port = 2222
    cfg.root = "/srv/drop"
    mut srv := sftpd.New(cfg)
    if not sftpd.Listen(srv):
        ret 1
    end
    handled := sftpd.ServeOnce(srv)
    println "one connection served:", handled
    sftpd.Serve(srv)
    sftpd.Close(srv)
    ret 0
end

Serve

func Serve(srv &: Server)
Serves connections one after another until the server is closed.

The example for this item is shown with the ones above: sftpd-Serve.salam