sftp-fail2ban

sftp-fail2ban

Docker app from bmartino1's Repository

Easy to use SFTP (SSH File Transfer Protocol) server with OpenSSH and Fail2ban installed for extra hardening against brute force attacks.

Overview
Easy to use SFTP (SSH File Transfer Protocol) server with OpenSSH and Fail2ban installed for extra hardening against brute force attacks. Forked from atmoz/sftp. Based on Debian Slim Image. *Shared Path is an example. You must replace the host path with the path to a folder to share AND change the user in the container path to the name of a user account configured in users.conf. See the GitHub page for more info: https://github.com/bmartino1/sftp-debian.

SFTP with Fail2Ban — Debian Forky

Docker Hub GitHub Unraid

SFTP-only file transfer using Debian Forky/testing, OpenSSH, OpenSSL, Fail2Ban, and rsyslog. Includes hardened SSH settings, persistent configuration, file-based security logs, and four Fail2Ban jails.

Unraid support forum

Distribution note: Debian Forky/testing is rolling, not stable/LTS. Package versions can change between builds; test updates before public-facing deployment.

Docker Features

  • Base: Debian Forky/testing Slim (rolling; not an LTS/stable distribution)
  • Hardened default ssh config
  • Fail2ban
  • Persistent /config for user accounts, host keys, logs, Fail2Ban configuration and runtime diagnostics
  • Four polling-based Fail2Ban jails, tested with actual firewall ban enforcement
  • Optional timed APT updates and restart-required notices

Environment variables

Name Default Description
TZ America/Chicago Container timezone, e.g. America/Chicago.
AUTO_UPDATE suite Update policy: none, suite, custom.
DEFAULT_ADMIN true Legacy setting retained for compatibility; explicitly supplied valid ADMIN_PASS is synchronized regardless of this flag.
ADMIN_USER admin Account name synchronized into persistent users.conf on each startup when a valid ADMIN_PASS is supplied.
ADMIN_PASS (unset) Valid supplied password overrides the matching persistent account at every startup; known default/placeholder passwords are rejected.
SFTP_USERS (unset) Legacy whitespace-separated account definitions merged into persistent users.conf on every startup; other users are retained. Format: user:pass[:e][:uid][:gid][:dirs].
AUTO_UPDATE_INTERVAL_HOURS 0 (including when omitted) Optional unattended APT upgrade interval in hours. 0 disables periodic updates; a positive integer enables them. OpenSSH package changes write /config/debug/restart-required.txt without automatically restarting SSHD.
PASSWORD_AUTH (unset) Force OpenSSH password auth policy: yes/no.
ALLOW_USERS (unset) Space-separated allowlist of SSH users (e.g. admin alice).
F2B_CONFIG_MODE symlink Populate /etc/fail2ban from /config/fail2ban: symlink | overlay | noclobber | replace.
DISABLE_IMKLOG true Disable rsyslog imklog module (avoids /proc/kmsg noise in containers).
MODE start start = normal boot; seed = prepare configs then exit.
TAIL_LOGS true Mirror selected logs to docker logs (files are always written to /config/log/…).
LOG_STREAMS auth,fail2ban Comma-separated selection for TAIL_LOGS: any of auth, fail2ban, whois.
DEBUG_TESTING false When true, runs fail2ban dry-run and dumps effective sshd config to /config/debug/.
MAIL_SERVER false When true, keeps Fail2Ban mail actions; otherwise writes zz-nomail.local to disable mail.
CLEAR_LOGS false When true, archives previous run logs to /config/log/archive/<name>.<UTC-timestamp>.log and truncates current logs on boot.

User accounts: /config/sshd/users.conf remains the persistent account database. On every container startup, explicitly supplied, valid ADMIN_USER/ADMIN_PASS and SFTP_USERS records update matching entries in that file even if their values have not changed since the prior start. The admin account retains its existing UID/GID/share settings; a newly created admin uses 1000:100:sftp. Unrelated users are preserved. If both inputs name the admin, ADMIN_USER/ADMIN_PASS takes precedence. An absent ADMIN_PASS leaves existing admin credentials unchanged, while known placeholder values (including password, admin, change-me-now, REPLACE_WITH_UNIQUE_PASSWORD) are refused and cannot seed the account. Manual changes to environment-managed entries will be overwritten on the next restart while those environment values remain configured; for file-only management, remove or unset the corresponding environment variable. Existing UID/GID mismatch protections still apply. Never expose a public listener with default credentials. SFTP chroot homes must remain root:root (0755), while shares retain their existing host permissions unless explicitly changed.

Notes

  • Persistent logs always in /config/log/.
  • AUTO_UPDATE=custom runs /config/updateapps.sh.
  • MAIL_SERVER=true allows custom mail actions when mail delivery is separately configured.
  • By default, mail actions are disabled, but events continue to be logged.

Updating and running with Docker Compose

The repository-root docker-compose.yml includes the existing configuration comments, both a local build: . and a Docker Hub image: tag, and the optional AUTO_UPDATE_INTERVAL_HOURS setting.

git clone https://github.com/bmartino1/sftp-debian.git
cd sftp2
# Edit docker-compose.yml host volume paths and create a valid users.conf.
# First boot creates a credential-free template unless explicit Unraid admin settings seed it.
docker compose up -d --build

Unless you provide valid Unraid ADMIN_USER/ADMIN_PASS settings on a fresh config, you must populate /config/sshd/users.conf with your own account entry (e.g. admin:STRONG_UNIQUE_PASSWORD:1000:100:sftp) before the SFTP daemon will start. On Unraid, the sample config location is /mnt/user/appdata/sftp-fail2ban/sshd/users.conf. Protect it with mode 0600. After editing credentials, run docker compose restart to apply them.

To use the published Docker Hub image instead, comment out the Compose build: . line and run docker compose pull && docker compose up -d.

Startup AUTO_UPDATE=suite updates the configured Debian suite. AUTO_UPDATE_INTERVAL_HOURS is optional: if it is not supplied, its default is 0, so periodic checks are disabled. Set 24 to opt into a check approximately every 24 hours. The timed process does not automatically restart SSHD; it records an OpenSSH package change under /config/debug/restart-required.txt. Schedule image rebuilds and controlled restarts to activate updated binaries and libraries. Debian testing package updates can introduce breaking changes.

The updater is stored at scripts/update-inplace.sh and installed into the image as /usr/local/bin/update-inplace.sh. AUTO_UPDATE=custom executes /config/updateapps.sh if present.

Run container from Docker registry

Use a dedicated /config mount, create a valid /config/sshd/users.conf, and then start:

docker run -d --name sftp-fail2ban \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  -v /host/config/path:/config \
  -p 22:22 bmmbmm01/sftp2:latest

Inline user arguments are intentionally ignored; users.conf controls user creation and password synchronization.

Volumes, Paths, and Ports

Volumes

Volume Required Function Example
config Yes SSH and Fail2ban config files /your/config/path/:/config

Paths/Files

Build-time diagnostics are under /opt/debug/ (including build-versions.txt); persistent runtime diagnostics go to /config/debug/. Mount /config to retain accounts, keys, logs and Fail2Ban state across container replacements. The entrypoint seeds missing files and respects existing persistent configurations. F2B_CONFIG_MODE controls how packaged and persistent Fail2Ban settings are wired.

The entrypoint seeds missing configuration files, but SSHD will not start until users.conf contains a valid account. Existing persisted configuration files are not silently replaced.

SSH

Path Required Function
/config/sshd/keys Yes* SSH host keys directory
/config/sshd/sshd_config Yes* SSH server configuration file
/config/sshd/users.conf Yes SSH users config file
/config/userkeys No SSH user keys directory

Fail2Ban

Path Required Function
/config/fail2ban Yes Fail2ban config and log directory
/config/fail2ban/fail2ban.local No* Fail2Ban config file
/config/fail2ban/jail.local No* Fail2Ban jail config file
/config/fail2ban/fail2ban.sqlite3 No* Auto generated Fail2Ban SQLite DB for persistent bans between reboots

*These files are automatically created if they are not present when the container is started

Ports

The OpenSSH server runs by default on port 22. You can forward the container's port 22 to any host port if using the docker bridge network and docker NAT system. Changing only the Docker host port (for example, 2222:22) does not require changing SSHD or Fail2Ban. If you change the internal SSHD port, update the corresponding Fail2Ban port.

Port Proto Required Function Example
22 TCP Yes SSH Port 2222:22

Customizing

Sharing a directory from your computer

Mount the host path to a folder inside the user's home directory. Example shows mounting host upload directory to upload directory in user home folder. Alternatively, see the bindmount dirs from another location below for an example of mapping to a different directory and using scripts to mount dirs inside users home folders.

docker run -d --name sftp-fail2ban \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  -v /host/config/path:/config \
  -v /host/upload:/home/user/upload \
  -p 2222:22 bmmbmm01/sftp2:latest

Create the account in /host/config/path/sshd/users.conf (for example user:YOUR_STRONG_PASSWORD:1001:100:upload). User arguments passed to docker run are ignored.

Add SSH users

Add users to /config/sshd/users.conf with the following pattern:

user:pass:UID:GID

Example:

user:pass:1001:100
user2:abc:1002:100
user3:xyz:1003:100

Password updates: For accounts managed by Docker/Unraid variables, change the environment value and recreate the container. For file-only accounts, edit users.conf and restart. Supplying the environment value overrides the same user in users.conf on every startup. The hardened default has PubkeyAuthentication no. Blank-password, key-only accounts require explicitly changing SSHD configuration.

Encrypted password

Add :e behind password to mark it as encrypted. Use single quotes if using a terminal instead of users config file.

foo:$1$0G2g0GSt$ewU0t6GXG15.0hWoOX8X9.:e:1001

Prefer a modern SHA-512 crypt hash, generated with openssl passwd -6, and keep users.conf at mode 0600.

Optional SSH public-key authentication

The default hardened profile disables public-key authentication. If you explicitly enable it in SSHD, place public keys with the user's name in /config/userkeys directory. The keys must be matched with a user's names and a .pub extension. These are copied to .ssh/authorized_keys for the user during container start.

Example:

user.pub

Providing your own SSH host key (recommended)

This container will generate new SSH host keys at first run in /config/sshd/keys. You can place your own sshd keys in this folder, and they will be copied to /etc/ssh/ when the container runs.

Tip: you can generate your keys with these commands:

ssh-keygen -t ed25519 -f ssh_host_ed25519_key < /dev/null
ssh-keygen -t rsa -b 4096 -f ssh_host_rsa_key < /dev/null

Execute custom scripts or applications

Put your programs in /config/sshd/scripts and it will automatically run when the container starts. See next subsection for an example.

Bindmount dirs from another location

Prefer ordinary Docker bind mounts for sharing directories. An advanced custom script under /config/sshd/scripts/ can use mount --bind with suitable privileges, but review this carefully.

#!/usr/bin/env bash
# Example only; requires CAP_SYS_ADMIN. Prefer Docker volumes instead.
mkdir -p /home/admin/tools
mount --bind /data/admin-tools /home/admin/tools

NOTE: Using mount requires CAP_SYS_ADMIN and compatible container security policy. See this answer for more information.

Note: OpenSSH and OpenSSL are provided by Debian Forky/testing packages, which are updated through APT; package versions may lag upstream releases. Rebuild and verify the container regularly. No upstream tarball is compiled during container startup.

Building the container yourself

git clone https://github.com/bmartino1/sftp-debian.git
cd sftp2
docker compose up -d --build

Review the root docker-compose.yml, adjust host paths, and populate users.conf before starting. To build without Compose, run docker build -t sftp2-local ..

Categories

Download Statistics

5,196
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
bmmbmm01/sftp2:latest
Last Updated2026-10-30
First Seen2025-10-16

Runtime arguments

Network
bridge
Shell
bash
Privileged
false
Extra Params
--hostname sftp --cap-add=NET_ADMIN --cap-add=NET_RAW

Template configuration

SSH PortPorttcp

Docker bridge network set SSH/SFTP port

Target
22
Default
22
Value
22
AdminDataPathrw

Default admin user's host folder/file access

Target
/home/admin/sftp
Default
/mnt/user/
Value
/mnt/user/
AppDataPathrw

Persistent config: users.conf, SSH host keys, Fail2Ban settings and logs

Target
/config
Default
/mnt/user/appdata/sftp-fail2ban
Value
/mnt/user/appdata/sftp-fail2ban
TimeZoneVariable
Target
TZ
Value
America/Chicago
AUTO_UPDATEVariable

true Runs /stage/updateapps.sh if present custom Runs /config/updateapps.sh if present false or empty skips updates

Default
true
Value
true
LOG_STREAMSVariable

auth,fail2ban,whois (comma-separated list for Docker stdout) Tail log streams.

Default
auth,fail2ban,whois
Value
auth,fail2ban
ADMIN_PASSVariable

REQUIRED: Enter a unique password before first start. No default password is supplied; this synchronizes to /config/sshd/users.conf on startup.

PUIDVariable

User root

Default
99
Value
0
PGIDVariable

User root

Default
100
Value
0
ADMIN_USERVariable
Default
admin
Value
admin
DEBUG_TESTINGVariable

Preflight checks (makes sure Fail2ban and sshd will work) (writes to /config/debug when true), false by default

Default
false
Value
true
TAIL_LOGSVariable

T/F enable Docker log showing tail logs. This doesn't stop them from writing to the log folder.

Default
true
Value
true
CLEAR_LOGSVariable

At container restart, truncate logs in the log folder. This will move old logs within the log folder; no logs are removed.

Default
false
Value
true
F2B_CONFIG_MODEVariable

How to handle /config Fail2ban files # ===== Fail2Ban config wiring ===== # How /etc/fail2ban is populated from /config/fail2ban: # - symlink (source of truth = /config) # - overlay (defaults + then /config over) # - noclobber (defaults + non-clobber copy from /config) # - replace (use /config only)

Default
noclobber
Value
symlink