Edit File: README.Authentication-Modules
------------------------ AUTHENTICATION MODULES ------------------------ Anybody can add new custom authentication methods to Pure-FTPd without recompiling anything, using "authentication modules". To enable it, you must ./configure with --with-extauth, or --with-everything. Linux binary packages have it enabled by default. Here's how they are working: 1) A client connects to the FTP server and issues a login/password pair. 2) The FTP server connects to a local separate daemon, called 'pure-authd'. Data transmitted to that daemon is: user's login, user's password, the IP address that user connected to, the local port that user connected to and the user's remote IP address. 3) pure-authd spawns an authentication program. It can be anything, including a shell script. The program is given the collected info (login, password, IP addresses, etc) as environment variables. 4) The authentication program replies (to the standard output) with the user's home directory, quota, ratio, bandwidth and if authentication was successful or not. 5) pure-authd relays this info to pure-ftpd. This method is a bit slower than built-in authentication methods. But it's very flexible as anyone can easily write his own authentication programs. And they can run non-root, chrooted, with limited capabilities, etc. Communication between pure-ftpd and pure-authd is done through a local Unix socket. It's recommended to put that socket in a directory where non-trusted users have no write access to. Authentication programs can read the following environment variables to get info about the user trying to authenticate: AUTHD_ACCOUNT AUTHD_PASSWORD AUTHD_LOCAL_IP AUTHD_LOCAL_PORT AUTHD_REMOTE_IP AUTHD_ENCRYPTED They are self-explanatory. Previous global environment variables aren't cleared when the script is called. The content of these variables is _not_ quoted. They may contain special characters. They are under the control of a possibly malicious remote user. The program must respond on the standard output with lines like: auth_ok:1 uid:42 gid:21 dir:/home/j end Note the final 'end' keyword. It's mandatory. Here's the list of recognized tokens ('xxx' has of course to be filled): * auth_ok:xxx If xxx is 0, the user was not found (the next authentication method passed to pure\-ftpd will be tried) . If xxx is \-1, the user was found, but there was a fatal authentication error: user is root, password is wrong, account has expired, etc (next authentication methods will not be tried) . If xxx is 1, the user was found and successfully authenticated. * uid:xxx The system uid to be assigned to that user. Must be > 0. * gid:xxx The primary system gid. Must be > 0. * dir:xxx The absolute path to the home directory. Can contain /./ for a chroot jail. *slow_tilde_expansion:xxx (optional, default is 1) When the command 'cd ~user' is issued, it's handy to go to that user's home directory, as expected in a shell environment. But fetching account info can be an expensive operation for non-system accounts. If xxx is 0, 'cd ~user' will expand to the system user home directory. If xxx is 1, 'cd ~user' won't expand. You should use 1 in most cases with external authentication, when your FTP users don't match system users. You can also set xxx to 1 if you're using slow nss_* system authentication modules. * throttling_bandwidth_ul:xxx (optional) The allocated bandwidth for uploads, in bytes per second. * throttling_bandwidth_dl:xxx (optional) The allocated bandwidth for downloads, in bytes per second. *user_quota_size:xxx (optional) The maximal total size for this account, in bytes. * user_quota_files:xxx (optional) The maximal number of files for this account. * ratio_upload:xxx and radio_download:xxx (optional) The user must match a ratio_upload:ratio_download ratio. * per_user_max:xxx (optional) The maximal authorized number of concurrent sessions. ------------------------ EXAMPLE ------------------------ Here's a very basic example. Our sample authentication program will only accept user 'john' with any password and return a fixed home directory and uid/gid. #! /bin/sh if test "$AUTHD_ACCOUNT" = "john"; then echo 'auth_ok:1' echo 'uid:69' echo 'gid:42' echo 'dir:/tmp' else echo 'auth_ok:0' fi echo 'end' Let's say we save this file as /usr/bin/ftp-auth-handler Now, we have to run pure-authd and pure-ftpd, to connect them through a local socket and to tell pure-ftpd to use our external authentication module: pure-authd -s /var/run/ftpd.sock -r /usr/bin/ftp-auth-handler & pure-ftpd -lextauth:/var/run/ftpd.sock & That's all. Now, we can only log in as 'john', as all FTP authentication is done by the shell script.