Skip to content

Configuration

uFTP is configured with one file, uftpd.cfg. The server reads ./uftpd.cfg (the directory you start it from) if that file exists, otherwise /etc/uftpd.cfg. Lines that start with # are comments. Restart uFTP to apply a change.

The sample file shipped with the source (uftpd.cfg) describes every option. This page explains them in more detail.

Server

Option Default Meaning
FTP_PORT 21 TCP port of the control connection. Use a port above 1024 to run without root.
SINGLE_INSTANCE true Only one server can run at a time.
DAEMON_MODE true Run in the background. Set false to run from a console, or with systemd.
RESPAWN_PROCESS true A supervisor process restarts the server if it stops. Every restart is logged. Set false with systemd.

Connections and limits {#limits}

Option Default Meaning
MAXIMUM_ALLOWED_FTP_CONNECTION 50 Maximum number of clients together. See Memory.
MAX_CONNECTION_NUMBER_PER_IP 10 Connections from one address together (0 = no limit).
MAX_CONNECTION_PER_ACCOUNT 0 Sessions of one user from any address (0 = no limit). MAX_CONNECTION_PER_ACCOUNT_n sets the limit of USER_n alone.
MAX_CONNECTION_RATE_PER_IP 0 New connections per minute from one address (0 = no limit). The ones over the limit get 421. An IPv6 address counts as its /64 network.
MAX_CONNECTION_TRY_PER_IP 10 Failed logins before the address is blocked for 5 minutes (0 = no limit). An IPv6 address counts as its /64 network.
IDLE_MAX_TIMEOUT 330 Seconds of inactivity before a client is disconnected (0 = never).
LOGIN_TIMEOUT 60 Seconds a client may stay connected without logging in (0 = no limit). NOOP does not extend it.
MIN_FREE_SPACE_MB 0 STOR and APPE are refused (452) when the free space of the disk is below this many megabytes, and an upload in progress is stopped. 0 = no check. 1024 or more is reasonable, because the server runs as root.

FileZilla and the limits

FileZilla with 10 simultaneous transfers uses 11 sessions at once, and it can open about 18 connections in a few seconds. Set MAX_CONNECTION_NUMBER_PER_IP and MAX_CONNECTION_RATE_PER_IP accordingly if your users transfer many files together.

Memory {#memory}

The memory of every slot (about 37 KB) is reserved when the server starts. 50 slots are about 2 MB, 1,000 slots about 37 MB and 12,000 slots about 450 MB. On top of that a connection uses about 1 KB, or about 23 KB with TLS. Set MAXIMUM_ALLOWED_FTP_CONNECTION to what you need, not more.

Passive mode and NAT {#passive}

Option Default Meaning
RANDOM_PORT_START, RANDOM_PORT_END 10000, 50000 Range of the ports used for passive data connections. Forward the same range on your router.
SERVER_IP (not set) The address that PASV tells the clients, with commas: 192,168,1,1. Needed when the server is behind a NAT.
PASV_PROMISCUOUS false By default a data connection must come from the same address as the control connection (RFC 2577). Set true only behind NAT pools that use several outgoing addresses.

More in Behind a NAT or a firewall.

TLS

Option Default Meaning
CERTIFICATE_PATH /etc/uFTP/cert.pem The certificate.
PRIVATE_CERTIFICATE_PATH /etc/uFTP/key.pem The private key, without a passphrase.
FORCE_TLS false Refuse connections that do not use TLS.

Needs a build with OpenSSL. See TLS and certificates.

Logs {#logs}

Option Default Meaning
LOG_FOLDER /var/log/ Folder of the logs, one file a day: uftpLog_YYYY-MM-DD. It must end with /.
MAXIMUM_LOG_FILES 30 Days of logs to keep. 0 turns the logs off: only fatal errors are written, on stderr.

In the same folder uFTP keeps uftpLog.current, a link to the file of today that moves to the new file when a new day starts. Programs that follow a log (see fail2ban) should use this name, because the name of the file changes every day.

The log records startup, crashes (with a stack trace), restarts, the reason of a shutdown, logins, transfers, file changes, and why each connection was closed. Characters that are not printable in a user name or a path are shown as ?.

Users {#users}

Users are numbered from 0. Every user has a number n in the names of its options:

Option Required Meaning
USER_n yes The user name.
PASSWORD_n yes The password, or a hash (below).
HOME_n yes The directory the user can see. The user cannot leave it.
GROUP_NAME_OWNER_n no Group of the new files, an existing group of the system.
USER_NAME_OWNER_n no Owner of the new files, an existing user of the system. If it does not exist the files belong to root and the log says so at startup.
BLOCK_USER_n no A name that is never allowed to log in.
USER_0 = alice
PASSWORD_0 = a-long-secret
HOME_0 = /srv/ftp/alice
USER_NAME_OWNER_0 = alice
GROUP_NAME_OWNER_0 = alice

USER_1 = web
PASSWORD_1 = another-secret
HOME_1 = /var/www/html/
USER_NAME_OWNER_1 = www-data
GROUP_NAME_OWNER_1 = www-data

BLOCK_USER_0 = guest

If the owner options are missing, new files belong to the user and group of the server, usually root:root.

Hashed passwords

PASSWORD_n can be a hash instead of the password, so a copy of uftpd.cfg does not show the passwords. It needs a build with OpenSSL. uFTP uses PBKDF2-HMAC-SHA256.

./uFTP --hash-password

The program asks for the password twice and prints the line to write in the file:

PASSWORD_0 = $pbkdf2-sha256$100000$<salt>$<hash>

Plain passwords still work next to hashes. From a script, echo 'secret' | ./uFTP --hash-password reads the first line of the input.

The iterations

The number after pbkdf2-sha256$ is the number of iterations: how many times the calculation is repeated. A higher number makes every guess slower, for you and for anyone who steals the file and tries to guess the passwords. The default is 100,000. Choose another value with --iterations; it can be from 1 to 10,000,000:

./uFTP --hash-password --iterations 300000

The number is stored in the hash, so every user can have a different one, and you can change it at any time: make a new hash of the password with the new number and replace the line. The old hashes keep working.

Every login attempt costs this calculation, also a wrong password and a name that does not exist (uFTP does the same work for a name that does not exist, so the time of the reply does not tell which names exist). Measured on a 12-core desktop CPU:

Iterations Time of one check
100,000 (default) 0.03 s
310,000 0.07 s
600,000 0.14 s
1,000,000 0.23 s
5,000,000 1.1 s

A small board is several times slower: measure it on the machine that runs the server, with time (echo test | ./uFTP --hash-password --iterations 600000).

A higher number is not always better

The check runs in the thread that serves all the control connections: while it runs, no other client is served. At 0.14 s per check a client that tries wrong passwords can keep the server busy for that long at every attempt. A commonly cited recommendation for PBKDF2-HMAC-SHA256 is 600,000 iterations (OWASP), for sites that can afford the time. For uFTP, which serves every control connection in one thread, the default is a good balance for most sites; raise it only if the file can be stolen and you have few logins, and keep the check under about 0.1 s. Together with MAX_CONNECTION_TRY_PER_IP (failed logins before an address is blocked) and MAX_CONNECTION_RATE_PER_IP the cost stays under control.

If the users have different iterations, the check of a name that does not exist uses the highest of them, so the time stays the same for every name; use the same number for every user if you can.

A long, random password matters more than the iterations: 100,000 iterations slow a guess down, they do not make 123456 safe.

System users (PAM)

ENABLE_PAM_AUTH = true logs in the users of the system (/etc/passwd, /etc/shadow) instead of the list in the file. It needs a build with PAM (see Installation). uFTP uses the PAM service named sudo, so the policy of /etc/pam.d/sudo applies, and expired accounts are refused.

Full sample

The sample file with comments is in the source: uftpd.cfg.