atmoz/sftp Documentation

The project provides two main base images:

• debian / latest: Generally considered more stable. Security and bug fixes are added after each Debian release (approx. every 2 years).
• alpine: Significantly smaller (approx. 10x smaller than Debian). Has a faster release cycle (approx. every 6 months), resulting in newer versions of OpenSSH.

Choose alpine for minimal footprint and newer software, or debian for long-term stability.

You can define users in three ways:

1. Command arguments: Pass user strings directly to the container command.
2. SFTP_USERS environment variable: Set this variable in your container environment.
3. Config file: Mount a file at /etc/sftp/users.conf.

User Syntax: user:pass[:e][:uid[:gid[:dir1[,dir2]...]]] ...

• user: Username.
• pass: Password (use :e after the password to indicate it is encrypted).
• uid/gid: Manual UID/GID settings (useful for matching host filesystem permissions).
• dir1,dir2...: Directories created under the user's home directory with write permission.

To prevent 'Man-in-the-Middle' (MITM) warnings when recreating containers, mount your own host keys to /etc/ssh/ssh_host_*. This ensures a consistent server fingerprint.

Generate keys using:

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

docker run \
    -v <host-dir>/ssh_host_ed25519_key:/etc/ssh/ssh_host_ed25519_key \
    -v <host-dir>/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
    -v <host-dir>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    foo::1001

Any script or application placed in the /etc/sftp.d/ directory will be automatically executed when the container starts. This is useful for performing advanced setup tasks like bindmounting directories from other locations.

Note: If using the mount command within a script to bindmount directories, the container must be run with the CAP_SYS_ADMIN capability.

#!/bin/bash
# File mounted as: /etc/sftp.d/bindmount.sh

function bindmount() {
    if [ -d "$1" ]; then
        mkdir -p "$2"
    fi
    mount --bind $3 "$1" "$2"
}

bindmount /data/admin-tools /home/admin/tools

To use an encrypted password, append :e immediately after the password in the user string. If providing this via a terminal command, wrap the argument in single quotes to prevent shell expansion.

To generate an encrypted password using Python:

docker run --rm python:alpine python -c "import crypt; print(crypt.crypt('YOUR_PASSWORD'))"

docker run -v <host-dir>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    'foo:$1$0G2g0GSt$ewU0t6GXG15.0hWoOX8X9.:e:1001'

To allow SSH key authentication, mount public keys into the user's .ssh/keys/ directory inside the container. The container automatically appends these keys to the user's .ssh/authorized_keys file.

Note: You cannot mount the authorized_keys file directly because OpenSSH requires specific file permissions.

To disable password authentication and require only SSH keys, provide an empty password in the user string (e.g., user::uid).

docker run \
    -v <host-dir>/id_rsa.pub:/home/foo/.ssh/keys/id_rsa.pub:ro \
    -v <host-dir>/id_other.pub:/home/foo/.ssh/keys/id_other.pub:ro \
    -v <host-dir>/share:/home/foo/share \
    -p 2222:22 -d atmoz/sftp \
    foo::1001

To manage multiple users via a configuration file, mount a file to /etc/sftp/users.conf. Each line follows the syntax user:pass[:e][:uid[:gid[:dir1[,dir2]...]]].

Example users.conf content:

foo:123:1001:100
bar:abc:1002:100
baz:xyz:1003:100