Aegis documentation

#Cube: vsftpd

vsftpd 3 with virtual users: no system account per user, one FTP root each, PAM reading a pam_pwdfile file.

In the panel: FTP Manager → Users and Settings. Every write there is a task.

#Configuration

toml
[ftp]config_dir = "/aegis/config/vsftpd"pam_dir = "/etc/pam.d"pam_service = "aegis-vsftpd"guest_user = "aegis-ftp"home_base = "/aegis/data/ftp"passwd_file = "/aegis/config/vsftpd/ftpd.passwd"log_dir = "/aegis/logs/vsftpd"port = 21pasv_min = 40000pasv_max = 40100max_clients = 50max_per_ip = 5ssl_cert = "/aegis/config/vsftpd/ftp.crt"ssl_key = "/aegis/config/vsftpd/ftp.key"
KeyDefaultMeaning
config_dir/aegis/config/vsftpdvsftpd.conf, password file, empty/
pam_dir/etc/pam.dwhere the PAM service is written
pam_serviceaegis-vsftpdPAM service name vsftpd calls
guest_useraegis-ftpsystem account every virtual user maps to
home_base/aegis/data/ftpone directory per virtual user
passwd_file<config_dir>/ftpd.passwduser:hash lines read by pam_pwdfile
log_dir/aegis/logs/vsftpdtransfer log and keeper log
port21control connection
pasv_min, pasv_max40000, 40100passive data ports; open them in the firewall
max_clients50simultaneous connections
max_per_ip5connections per source address
ssl_cert, ssl_key<config_dir>/ftp.*local certificate copied there by configure

#Files

text
<ftp.config_dir>/├── vsftpd.conf               daemon configuration├── ftpd.passwd               user:hash lines, mode 0640├── empty/                    secure_chroot_dir, mode 0555├── ftp.crt / ftp.key         TLS material used by the daemon└── vsftpd.pid                written by the keeper<ftp.home_base>/└── <user>/                   one FTP root per user<ftp.log_dir>/└── vsftpd.log                transfer log/etc/pam.d/aegis-vsftpd       PAM service (``ftp.pam_service``)

#Commands

bash
aegis cubes vsftpd configure        # account, TLS, configuration, startaegis cubes vsftpd validate         # files present, binary runsaegis cubes vsftpd reload           # restart: configuration is read at startupaegis cubes vsftpd start|stop|restart|statusaegis cubes vsftpd users listaegis cubes vsftpd users add demo --password 'secret123'aegis cubes vsftpd users password demo --password 'new-secret'aegis cubes vsftpd users remove demoaegis cubes vsftpd expose

#Virtual users

users add:

  • validates the name ([a-z0-9._-], 32 characters at most);
  • hashes the password with openssl passwd -6 — pam_pwdfile accepts crypt(3)
  • hashes, and SHA512 is what the build supports everywhere;

  • appends user:hash to the password file;
  • creates <home_base>/<user> and hands it to the guest account.
  • users remove drops the line and leaves the files on disk.

    #How a login works

    text
    client → vsftpd → PAM (aegis-vsftpd) → pam_pwdfile → ftpd.passwd                 ↓          guest_enable maps the user onto <ftp.guest_user>                 ↓          local_root = <home_base>/<user>, chrooted

    Two details that are easy to get wrong:

  • local_enable=YES is required even with guest_enable=YES: without it
  • vsftpd answers 500 OOPS: both local and anonymous access disabled! at the banner.

  • The guest account needs a home directory. vsftpd chdirs there before it
  • applies local_root; a missing home is 500 OOPS: cannot change directory.

    #PAM module

    The built module lives in the application prefix, but PAM only searches the system module directory. The generated service therefore references it by absolute path:

    text
    auth     required  /aegis/apps/ftp/pam-pwdfile/2.0/lib/security/pam_pwdfile.so pwdfile=/aegis/config/vsftpd/ftpd.passwd

    #Build

    The distribution tarball ships with #undef VSF_BUILD_SSL, so the profile applies two patches:

    PatchWhy
    capabilities.patchthe link helper never looks in the multiarch libcap directory
    ssl.patchdefines VSF_BUILD_SSL; without it ssl_enable=YES exits with status 2
    ssl-deprecated.patch#define OPENSSL_SUPPRESS_DEPRECATED in ssl.c, because the Makefile compiles with -Werror
    ssl-declaration.patchfixes the setup_bio_callbacks() prototype: C23 (GCC 15) treats f() as f(void) and -Werror rejects the mismatch

    The Makefile assigns CFLAGS, IFLAGS and LDFLAGS itself, so the vendored OpenSSL paths are passed on the command line ([make] args) and the binary ends up with a RUNPATH into /aegis/apps/libs/openssl/3.5/lib.

    #expose

    bash
    aegis cubes vsftpd exposecube           vsftpdinstalled      /aegis/apps/ftp/vsftpd/3.0configuration  /aegis/config/vsftpdstate          running pid 894xxxconfig         /aegis/config/vsftpd/vsftpd.confpam            /etc/pam.d/aegis-vsftpdusers          1home           /aegis/data/ftptls            /aegis/config/vsftpd/ftp.crt

    #Notes

  • write_enable=YES is set: vsftpd defaults to read-only.
  • Passive ports 40000-40100 must be open in the firewall for clients behind
  • NAT.

  • The daemon is restarted on every configure; it reads its configuration only
  • once, at startup.