timoreymann/chrooted-ftp repository overview

⁠chrooted-ftp

A dead simple alpine-based docker container to allow users only access their own home directory.

⁠Features

• slim FTP server
• SFTP support
• support for passive mode
• every user is jailed into his own root directory

⁠Usage

⁠Prepare

1. Add user entry in form username:password into a file mounted under /opt/chrooted-ftp/users.
2. Mount the desired host volume under /data/username
3. Fire up the server.

⁠Usage with FTP

1. Expose port 21 (also see the sample docker-compose)
2. Your user can connect to the ftp server, only seeing their files

⁠Usage with SFTP

1. Expose port 2022 (also see the sample docker-compose)
2. If you want to keep the host keys across restarts make sure to mount /opt/chrooted-ftp/ssh_hostkeys
3. Your user can connect to the sftp server on port 2022, the root directory /data contains all files

⁠Sample docker-compose

version: '3.2'
services:
  ftp:
    image: timoreymann/chrooted-ftp
    environment:
      - "BANNER=Welcome to my dockerized FTP!"
    # USER_FTP_POSTFIX determines the ftp directory inside user home directory and defaults to /data if not set
    # If NO_USER_FTP_POSTFIX is set, USER_FTP_POSTFIX is disabled and the user home directory is exposed over ftp
    # - USER_FTP_POSTFIX=/data
    # - NO_USER_FTP_POSTFIX=true
  
    # optional and only used for passive ftp, defaults to 127.0.0.1
    # - PUBLIC_HOST=custom-host.domain.tld 
    ports:
      # ftp control
      - "21:21"
      # active ftp
      - "20:20"
      # passive ftp ports, may differ if you configured them differently with PASSIVE_MIN_PORT_*
      - "10090-10100:10090-10100"
      # sftp
      - "2022:2022"
    volumes:
      # Sample mount for user foo
      - /var/www/html:/data/foo
      # Mount user list
      - ./ftp_users:/opt/chrooted-ftp/users
      # Make sure to keep host keys across restarts
      - ./ssh_host_keys:/opt/chrooted-ftp/ssh_hostkeys

⁠Configuration

⁠Users

Users can be configured using the /opt/chrooted-ftp/users file.

The syntax is username:password, once per line.

There is also the default user bob with password s3cr3tCand!. This user is gone at the moment you mount the users file.

If using files is not your thing you can also create users with env vars, see the list in General settings⁠ for more information. Both can be used together, so you can use env vars and/or file-based user creation.

⁠FTP

You can further configure the ftp server using the following environment variables:

⁠SFTP

⁠General settings

⁠Ports

Default ports are:

I recommend exposing them as they are to the host, but you can also change them on the host.

See docker docs⁠ for more information.

For example usage, see the docker-compose example file above.

⁠Motivation

The problem this container is solving is the following: I want to provide ftp for some users, but i dont want to configure the chroot stuff and so on. So this container is doing exactly that. You can mount /data as your volume the subfolders are per user. So you can mount for example a website for a user under /data/bob and your host volume is /var/www/bobs.homepage.digital. Its just that simple.

⁠Documentation

⁠Under the hood

Under the hood the image is based on alpine and vsftpd. So it size and resource usage is really low.

⁠Chroot(ing)

VSFTPD and SFTP work completely different when it comes to chroot.

VSFTPD works with the user homes out of the box while SFTP chroot requires the common start folder to be owned by root.

To make it work with both, the structure is like this:

/data           | user root
    <user>      | Home folder, owned by root:root
        /data   | Data folder, owned by <user> - override with USER_FTP_POSTFIX (or disable with NO_USER_FTP_POSTFIX)

This structure allows FTP to acess the data directly, while via SFTP you need to prepend the path /data

⁠Contributing

I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:

• Reporting a bug
• Discussing the current state of the configuration
• Submitting a fix
• Proposing new features
• Becoming a maintainer

To get started please read the Contribution Guidelines⁠.

⁠Development

⁠Requirements

• Docker⁠