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.