Aegis documentation

#vsftpd

The vsftpd cube owns the FTP server and its virtual users. It renders vsftpd.conf and a PAM service under ftp.config_dir (/aegis/config/vsftpd) and ftp.pam_dir, keeps the password file at ftp.passwd_file (mode 0640), and copies the TLS certificate and key to stable paths inside the configuration directory. Each user gets a directory under ftp.home_base (/aegis/data/ftp/<user>), owned by the single guest account ftp.guest_user (aegis-ftp); no system account is created per user.

Authentication goes through pam_pwdfile, one user:SHA512-crypt line per virtual user. There is no database. The daemon listens on ftp.port (default 21) and runs as the keeper service aegis-vsftpd; it reads its configuration once at startup, so configure and reload both restart it.

#Common commands

Cube operations share one wrapper: ✔ vsftpd: <detail> on success, ✖ <message> on failure (exit 1), and {"ok": true, "cube": "vsftpd", "result": "<detail>"} with global --json.

expose is the only verb that prints a block instead of that line.

VerbEffect
configurecreate the guest account and its home, ensure TLS material, render both files, restart or start
validatecheck both config files, the password file and the TLS pair, run vsftpd -v
reloadrestart; the daemon has no reload path
statusread config/vsftpd.pid: running (pid N) or stopped
startstart the daemon through the keeper
stopSIGTERM, then SIGKILL after 15 seconds
restartstop, then start
exposeprint paths, user count and TLS paths, then publish the daemon
helpprint the command list with examples

#configure

bash
aegis cubes vsftpd configureaegis --json cubes vsftpd configure

Creates the empty chroot directory with mode 0555, an empty password file when there is none, and copies ssl.local material to ftp.ssl_cert and ftp.ssl_key (key mode 0600). A running daemon is restarted, not reloaded.

text
✔ vsftpd: configuration present, 2 users{"ok": true, "cube": "vsftpd", "result": "configuration present, 2 users"}

#validate

bash
aegis cubes vsftpd validateaegis --json cubes vsftpd validate

vsftpd has no configuration test, so the files, the TLS pair and the binary are checked instead.

text
✔ vsftpd: configuration present, 2 users{"ok": true, "cube": "vsftpd", "result": "configuration present, 2 users"}

#reload

bash
aegis cubes vsftpd reloadaegis --json cubes vsftpd reload

A restart. A stopped daemon fails with vsftpd is not running.

text
✔ vsftpd: stopped (pid 2001), started (pid 2022){"ok": true, "cube": "vsftpd", "result": "stopped (pid 2001), started (pid 2022)"}

#status

bash
aegis cubes vsftpd statusaegis --json cubes vsftpd status
text
✔ vsftpd: running (pid 2001){"ok": true, "cube": "vsftpd", "result": "running (pid 2001)"}

#start

bash
aegis cubes vsftpd startaegis --json cubes vsftpd start
text
✔ vsftpd: started (pid 2001){"ok": true, "cube": "vsftpd", "result": "started (pid 2001)"}

#stop

bash
aegis cubes vsftpd stopaegis --json cubes vsftpd stop

Active clients lose their connection; queued retries belong to the client.

text
✔ vsftpd: stopped (pid 2001){"ok": true, "cube": "vsftpd", "result": "stopped (pid 2001)"}

#restart

bash
aegis cubes vsftpd restartaegis --json cubes vsftpd restart
text
✔ vsftpd: stopped (pid 2001), started (pid 2044){"ok": true, "cube": "vsftpd", "result": "stopped (pid 2001), started (pid 2044)"}

#expose

bash
aegis cubes vsftpd exposeaegis --json cubes vsftpd expose
text
cube           vsftpdinstalled      /aegis/apps/ftp/vsftpd/3.0configuration  /aegis/config/vsftpdstate          running (pid 2001)pid            2001log            /aegis/logs/vsftpd/vsftpd-keeper.logconfig         /aegis/config/vsftpd/vsftpd.confpam            /etc/pam.d/aegis-vsftpdusers          2home           /aegis/data/ftptls            /aegis/config/vsftpd/ftp.crtkey            /aegis/config/vsftpd/ftp.keypublished      /aegis/bin/vsftpd
text
{"ok": true, "cube": "vsftpd", "installed": "/aegis/apps/ftp/vsftpd/3.0", "configuration": "/aegis/config/vsftpd", "state": "running (pid 2001)", "pid": "2001", "log": "/aegis/logs/vsftpd/vsftpd-keeper.log", "config": "/aegis/config/vsftpd/vsftpd.conf", "pam": "/etc/pam.d/aegis-vsftpd", "users": "2", "home": "/aegis/data/ftp", "tls": "/aegis/config/vsftpd/ftp.crt", "key": "/aegis/config/vsftpd/ftp.key", "published": "/aegis/bin/vsftpd"}

#help

bash
aegis cubes vsftpd helpaegis cubes help vsftpd
text
ℹ Vsftpd — FTP server with virtual usersCommands  validate   Check the configuration  reload     Reload the running daemon  configure  Write the configuration and TLS material  start      Start the daemon  stop       Stop the daemon  status     Show whether the daemon runs  restart    Restart the daemon  expose     Show where it is installed and how it runs  users      Manage virtual FTP users  help       Show every command with examples

The examples block follows.

#Virtual users

text
aegis cubes vsftpd users  Manage virtual FTP usersCommands  list      List users  add       Create a user  remove    Delete a user  password  Set a user passwordRun 'aegis cubes vsftpd users <command> --help' for the options of one command.

#users list

bash
aegis cubes vsftpd users listaegis --json cubes vsftpd users list

Reads the password file, so it works with the daemon stopped. It takes no options.

text
✔ vsftpd: demo, upload{"ok": true, "cube": "vsftpd", "result": "demo, upload"}

#users add

bash
aegis cubes vsftpd users add demo --password 'secret123'aegis --json cubes vsftpd users add upload --password 'secret123'
OptionMeaning
nameuser name: lowercase, letters, digits, ., _, -
--passwordrequired; at least 8 characters, stored as SHA512-crypt

Creates the password line and the FTP root under ftp.home_base, owned by the guest account. The name is not a system account and cannot log in anywhere else.

text
✔ vsftpd: user demo created (/aegis/data/ftp/demo){"ok": true, "cube": "vsftpd", "result": "user upload created (/aegis/data/ftp/upload)"}

#users remove

Destructive. Deletes the user's line, so logins stop immediately. The FTP root and the files in it stay on disk.

bash
aegis cubes vsftpd users remove demoaegis --json cubes vsftpd users remove upload
ArgumentMeaning
namethe virtual user to delete
text
✔ vsftpd: user demo removed (home left in place){"ok": true, "cube": "vsftpd", "result": "user upload removed (home left in place)"}

#users password

bash
aegis cubes vsftpd users password demo --password 'new-secret'aegis --json cubes vsftpd users password upload --password 'new-secret'
OptionMeaning
namethe virtual user
--passwordrequired new password
text
✔ vsftpd: password updated for demo{"ok": true, "cube": "vsftpd", "result": "password updated for upload"}