ftpd
An FTP and FTPS server that shares a directory with a login, passive transfers and optional TLS.
import ftpd
This package is an FTP server written in Salam. Give it a root directory, a user and a password, call Listen and then Serve, and any FTP client can list, upload, download, rename and delete files below that directory. Paths are resolved inside the root, but a symbolic link inside it that points elsewhere is followed, so keep links out of a directory you serve. It is the other half of the ftp client package, and the two work together.
It speaks plain FTP and FTPS. Transfers use passive mode (PASV and EPSV) on a port range you choose, so open that range in the firewall. Login is either one configured user with a password, or anonymous access when allow_anonymous is on; with neither, nobody can log in. With a certificate and a key the server also takes explicit FTPS (AUTH TLS, then PROT P for the data connection) and, with implicit_tls, implicit FTPS where the connection is encrypted from the first byte.
What to know before you use it:
- There is one user.
userandpassworddescribe a single account; a list of accounts, per-user directories and permissions are not part of this package. - Clients are served one after another.
Servehandles one connection to the end before it accepts the next, so it suits a small drop box or a build artefact server, not a busy public one. - Plain FTP sends the password in the clear. Turn on
tls_enabledwithcert_fileandkey_file, and setrequire_tlsso that the server refusesUSERandPASSuntil the connection is encrypted. A client has to start TLS before it sends the password; a client that sends it first has already leaked it, sorequire_tlsprotects only clients that behave. - Port 0 picks a free port, and
Porttells you which. That is how the examples and the tests run without clashing with anything.
Serve a directory with a login
Make a configuration with NewConfig, set the root, the user, the password and the passive port range, create the server with New, and call Listen. Listen is false when the port is taken or you may not use it; check it before Serve, which runs until the server is stopped. Ports below 1024, including the usual 21, need extra rights on most systems, which is why the example uses 2121.
import ftpd
import env
func main:
mut cfg := ftpd.NewConfig()
cfg.host = "127.0.0.1"
cfg.port = 2121
cfg.root = "/srv/ftp"
cfg.user = "reports"
cfg.password = env.Get("FTP_PASSWORD")
if cfg.password.len() == 0:
println "set FTP_PASSWORD first"
ret 1
end
cfg.passive_start = 40000
cfg.passive_end = 40100
mut srv := ftpd.New(cfg)
if not ftpd.Listen(srv):
println "cannot listen on port", cfg.port
ret 1
end
println "serving", cfg.root, "on port", ftpd.Port(srv)
ftpd.Serve(srv)
ftpd.Close(srv)
ret 0
endThe example binds to the loopback address and reads the password from the FTP_PASSWORD variable, so it never listens for other machines with a password written in the page; plain FTP should not leave the machine, use FTPS for that. It runs until it is stopped, so it is only checked here. Point any client at it, for example the ftp package with Dial and Login using the same user and password.
Encrypt the connection with FTPS
A certificate and a private key in PEM files turn on TLS. A client then upgrades the connection with AUTH TLS and protects the file data with PROT P. require_tls goes one step further and refuses USER and PASS until that has happened, so the server will not even try a login on a plain connection, though a password a misbehaving client already sent is gone. With implicit_tls the server expects TLS from the very first byte, the older FTPS style that uses its own port.
import ftpd
import env
func main:
mut cfg := ftpd.NewConfig()
cfg.port = 2121
cfg.root = "/srv/ftp"
cfg.user = "reports"
cfg.password = env.Get("FTP_PASSWORD")
if cfg.password.len() == 0:
println "set FTP_PASSWORD first"
ret 1
end
cfg.tls_enabled = true
cfg.cert_file = "/etc/ssl/certs/ftp.crt"
cfg.key_file = "/etc/ssl/private/ftp.key"
cfg.require_tls = true
mut srv := ftpd.New(cfg)
if not ftpd.Listen(srv):
println "cannot listen on port", cfg.port
ret 1
end
ftpd.Serve(srv)
ret 0
endIf the certificate or the key cannot be read, TLS stays off even when tls_enabled is true, so test the setup with a real client once before you trust it.
Defaults and a free port
A fresh configuration listens on all interfaces on port 21, serves the current directory, and lets nobody in until you set a user or turn on anonymous access. Passive transfers use ports 40000 to 40100. The program below shows the defaults, then binds to port 0 on the loopback address to find out which port the system gave it. Nothing connects, so it runs without a network.
import ftpd
func main:
mut cfg := ftpd.NewConfig()
println cfg.port, cfg.root, cfg.allow_anonymous
println cfg.passive_start, cfg.passive_end, cfg.tls_enabled
cfg.host = "127.0.0.1"
cfg.port = 0
cfg.allow_anonymous = true
mut srv := ftpd.New(cfg)
println ftpd.Listen(srv)
println ftpd.Port(srv) > 0
ftpd.Close(srv)
println srv.running
endAfter Listen the configuration inside the server holds the real port, which is what Port returns. Close stops the server and releases the port.
Which function for which job
| Job | Use |
|---|---|
| Start from the defaults | NewConfig, then set the fields of Config |
| Create the server | New |
| Open the port | Listen, then Port to read it |
| Serve clients until stopped | Serve |
| Serve exactly one client | ServeOnce |
| Stop and free the port | Close |
Types
Config
struct Config| Name | Type | Description |
|---|---|---|
host | str = "0.0.0.0" | The address to listen on; 0.0.0.0 means every interface. |
port | int = 21 | The port to listen on; 21 by default, and 0 lets the system choose one. |
root | str = "." | The directory the clients see as /; nothing above it can be reached. |
allow_anonymous | bool = false | Lets clients log in as the anonymous user without a password; off by default. |
anonymous_user | str = "anonymous" | The name that counts as anonymous; anonymous by default. |
user | str = "" | The name of the one account that may log in with a password. |
password | str = "" | The password of that account. |
passive_start | int = 40000 | The first port of the range used for passive data connections; 40000 by default. |
passive_end | int = 40100 | The last port of that range; 40100 by default. |
tls_enabled | bool = false | Turns on FTPS; it needs cert_file and key_file as well. |
cert_file | str = "" | The path of the certificate in PEM form. |
key_file | str = "" | The path of the private key in PEM form. |
implicit_tls | bool = false | Expects TLS from the first byte of the connection, as implicit FTPS does. |
require_tls | bool = false | Refuses login until the connection has been encrypted. |
import ftpd
func main:
mut cfg := ftpd.NewConfig()
println cfg.host, cfg.port, cfg.root
println cfg.allow_anonymous, cfg.anonymous_user
println cfg.user == "", cfg.password == ""
println cfg.passive_start, cfg.passive_end
println cfg.tls_enabled, cfg.implicit_tls, cfg.require_tls
println cfg.cert_file == "", cfg.key_file == ""
cfg.user = "reports"
cfg.allow_anonymous = true
println cfg.user, cfg.allow_anonymous
endServer
struct Server| Name | Type | Description |
|---|---|---|
config | Config | The configuration the server was made with; after Listen its port is the real one. |
listener | tcp.Server | The listening socket. |
running | bool = false | True after Listen worked and until Close is called. |
tls_cfg | tls.ServerConfig | The TLS settings loaded from the certificate and key; empty when TLS is off. |
import ftpd
func main:
mut cfg := ftpd.NewConfig()
cfg.host = "127.0.0.1"
cfg.port = 0
cfg.root = "/tmp"
mut srv := ftpd.New(cfg)
println srv.running, srv.config.root
println ftpd.Listen(srv), srv.running
println ftpd.Port(srv) > 0, srv.config.port == ftpd.Port(srv)
ftpd.Close(srv)
println srv.running
endFunctions
NewConfig
func NewConfig(): ConfigThe example for this item is shown with the ones above: ftpd-Config.salam
New
func New(cfg: Config): ServerThe example for this item is shown with the ones above: ftpd-Server.salam
Listen
func Listen(srv &: Server): boolThe example for this item is shown with the ones above: ftpd-Server.salam
Close
func Close(srv &: Server)The example for this item is shown with the ones above: ftpd-Server.salam
Port
func Port(srv: Server): intListen when the configuration said 0.The example for this item is shown with the ones above: ftpd-Server.salam
ServeOnce
func ServeOnce(srv &: Server): boolimport ftpd
func main:
mut cfg := ftpd.NewConfig()
cfg.host = "127.0.0.1"
cfg.port = 2121
cfg.root = "/srv/ftp"
cfg.allow_anonymous = true
mut srv := ftpd.New(cfg)
if not ftpd.Listen(srv):
ret 1
end
handled := ftpd.ServeOnce(srv)
println "one client served:", handled
ftpd.Serve(srv)
ftpd.Close(srv)
ret 0
endServe
func Serve(srv &: Server)running becomes false or the listener fails.The example for this item is shown with the ones above: ftpd-Serve.salam