[[ch-ftp-reference]]
== FTP configuration

FTP users can be authenticated in two ways: on a per-domain basis, or
on a per-user-per-domain basis.  It is possible to enable other forms
of authentication too.

=== Per-domain authentication
(((config/,ftp-password)))

Basic per-domain authentication is controlled by the 'config/ftp-password' file.
This file contains the plain-text or hashed password for the FTP user
whose username is the domain name.  This user is limited to accessing
the [directory]'public' directory for that domain.

For example, '/srv/my-brilliant-site.com/config/ftp-password' contains
the password for the FTP user *my-brilliant-site.com*, and that user
will be limited to accessing
[directory]'/srv/my-brilliant-site.com/public'.

=== Multi-user authentication
(((config/,ftp-users)))

This authentication method is controlled by the 'config/ftp-users'
file.  This file contains more than just the password.  Each line in
the file represents a different user, and contains the username,
password, base directory, and quota.  Comments in the file start with
*#*.

--------------------------------------
# username:password:directory:quota
bab:babs password:/path/to/base:10M
--------------------------------------

The directory and quota fields are optional.  If the password field is
empty, the user will not be able to log in.  

In the above example, if that file was kept at
'/srv/my-brilliant-site.com/config/ftp-users' then the user
*babs@my-brilliant-site* would be able to log in with the password
*babs password*.  She'd be limited to the accessing files and
directories below [directory]'/path/to/base', and uploads to that that
directory would be prohibited if it contains more than 10 Megabytes of
data.

=== Other forms of authentication

It is possible to use the other forms of authentication provided by
Pure-FTPd.  The 
https://download.pureftpd.org/pub/pure-ftpd/doc/README.Virtual-Users[Pure-FTPd manual]
gives a good run down of all the various ways to do it.  Here the two
most common ways have been documented.

==== PureDB authentication

To enable authentication for virtual users, but would rather not use
the Symbiosis method, you can create a Pure FTPd authentication DB,
and use that.  To tell the server to authenticate against it, you can
run the following commands, as root.

----------
echo /etc/pure-ftpd/pureftpd.pdb > /etc/pure-ftpd/conf/PureDB
ln -s /etc/pure-ftpd/conf/PureDB /etc/pure-ftpd/auth/50puredb
serivce pure-ftpd-wrapper restart
---------

Then you can use the
http://manpages.debian.org/cgi-bin/man.cgi?query=pure-pw&apropos=0&sektion=0&manpath=Debian+8+jessie&format=html&locale=en[@pure-pw@]
command to add new users.  For example to add the user *foo*, you can
run:

---------
pure-pw useradd foo -u 1000 -g 1000 -d /path/to/home -m
---------

It will prompt you for the password, and then rebuild the password
file '/etc/pure-ftpd/pureftpd.pdb' automatically.

==== Pam authentication

If you would like to add normal PAM authentication, then you can run
the following commands as root.

----------
echo 1 > /etc/pure-ftpd/conf/PAMAuthentication
ln -s /etc/pure-ftpd/conf/PAMAuthentication /etc/pure-ftpd/auth/50pam
serivce pure-ftpd-wrapper restart
---------

Normal UNIX users should be able to log in now with their standard
passwords.

=== Quotas

There are two ways of specifying a quota.  The default quota for a
domain goes in 'config/ftp-quota'.  This controls the quota for the
per-domain user in [directory]'public', as well as the default quota
for users specified in 'config/ftp-users'.  Its format is the same as
that for <<s-email-quotas,email quotas>>.

For the multi-user configuration file, a user's quota can be specified
in the final field, again in the same format as that used for email
quotas.

=== FTP configuration layout

'config/ftp-password':: Domain-wide FTP user's password.
(((config/,ftp-password)))
'config/ftp-quota':: Default FTP quota for the domain.
(((config/,ftp-quota)))
'config/ftp-users':: Per-user configuration for a domain.
(((config/,ftp-users)))



