README.Virtual-Users

       ------------------------ VIRTUAL USERS ------------------------


Virtual users is a simple mechanism to store a list of users, with their
password, name, uid, directory, etc. It's just like /etc/passwd. But it's
not /etc/passwd. It's a different file, only for FTP.

It means that you can easily create FTP-only accounts without messing up
your system accounts.

In addition, virtual users files can store individual quotas, ratios,
bandwidth, etc. System accounts can't do this.

Thousands of virtual users can share the same system user, as long as they
all are chrooted and they have their own home directory.

*IMPORTANT* If you are planning to use the virtual users feature, and
unless your operating system already provides a secure password
hashing function, please install libsodium (http://doc.libsodium.org)
before compiling Pure-FTPd.

A good thing to do before using virtual users is to create a system user
for this. Of course, you can use any existing account like "nobody" (but not
root), but it's better to have a dedicated account.

Let's create an "ftpgroup" group and an "ftpuser" user.

Linux/OpenBSD/NetBSD/Solaris/HPUX/OSX/a lot of other Unix-like systems:

groupadd ftpgroup
useradd -g ftpgroup -d /dev/null -s /etc ftpuser

FreeBSD/DragonflyBSD:

pw groupadd ftpgroup
pw useradd ftpuser -g ftpgroup -d /dev/null -s /etc

Then, all maintenance of virtual users can be made with the "pure-pw"
command. You can also edit the files by hand if you want.

Files storing virtual users have one line per user. These lines have the
following syntax:

<account>:<password>:<uid>:<gid>:<gecos>:<home directory>:<upload
bandwidth>:<download bandwidth>:<upload ratio>:<download ratio>:<max number
of connections>:<files quota>:<size quota>:<authorized local IPs>:<refused
local IPs>:<authorized client IPs>:<refused client IPs>:<time
restrictions>

Fields can be left empty (exceptions: account, password, uid, gid, home
directory) .

Passwords are compatible with the hashing function used in /etc/passwd or
/etc/master.passwd.


    ------------------------ CREATING A NEW USER ------------------------


To add a new user, use the following syntax:

         pure-pw useradd <login> [-f <passwd file>] -u <uid> [-g <gid>]
                         -D/-d <home directory> [-c <gecos>]
                         [-t <download bandwidth>] [-T <upload bandwidth>]
                         [-n <max number of files>] [-N <max Mbytes>]
                         [-q <upload ratio>] [-Q <download ratio>]
                         [-r <allow client ip>/<mask>] [-R <deny client ip>/<mask>]
                         [-i <allow local ip>/<mask>] [-I <deny local ip>/<mask>]
                         [-y <max number of concurrent sessions>]
                         [-C <max number of concurrent login attempts>]
                         [-M <total memory (in MB) to reserve for password hashing>]
                         [-z <hhmm>-<hhmm>] [-m]

Let's create "joe", whose home directory will be /home/ftpusers/joe . The
system account associated with "joe" is "ftpusers".

            pure-pw useradd joe -u ftpuser -d /home/ftpusers/joe

Joe's password is asked twice.

With -d, joe will be chrooted. If you want to give joe access to the whole
filesystem, use -D instead of -d.

You don't need to create /home/ftpusers/joe if you run pure-ftpd with the
-j (--createhome) switch. With that switch, home directories will
automatically be created when users will log in for the first time.

The "-z" option allow a user to connect only during a range of day time.
For instance, with -z 0900-1800, joe will only be able to connect from 9 am
to 18 pm. Warning: a user that connected during authorized hours can
finish his session after these authorized hours.

-r and -R are handy to restrict where the user can connect from. They can be
followed by a simple IP/mask pair (-r 192.168.1.0/24), multiple pairs
separated by a coma (-r 192.168.1.0/24,10.1.0.0/16,127.0.0.1/32), single IPs
(-r 192.168.1.4,10.1.1.5), host names (-r bla.bla.net,yopcitron.com), or any
combination of those.

-y is to restrict the number of concurrent sessions a user can have
at the same time. '' or 0 mean unlimited. Avoid this feature on very loaded
servers. Use per-ip limits instead.

Ok, "joe" has been created. By default, the list of virtual users is stored
in the /etc/pureftpd.passwd file (you can of course change this with -f
<file>) .

Let's have a look at its content:

joe:$7$C6..../....swVShTUX9kLJepm0vvj7dUXPqtULzQ9G3GT/GAO3bd3$GMHJRyUdSRwNROunwtRbEDHlx5t3eNQew7bb1dz29K2:500:101::/home/ftpusers/joe/./:::::::::::::

Passwords are hashed with the most secure hash function your system supports.
Hashes are tried in this order: argon2, scrypt, bcrypt, SHA-512, MD5.

SHA-512 and MD5 should not be used any more. bcrypt requires crypt(3)
from the C library to support it, which is commonly the case on BSD
systems, but is only present on some Linux distributions.

Argon2 and scrypt are the recommended functions, and require pure-ftpd to be
compiled in presence of libsodium. Note that a login attempt will require up
to 64 Mb memory, and 100% of a CPU core. The number of simultaneously allowed
sessions should be tuned accordingly to avoid resources starvation.


       ------------------------ CHANGING INFO ------------------------


Once virtual users have been created, you can edit their info. For instance
you can add bandwidth throttling, change quotas, add their full name, update
ratio, etc.

The "pure-pw usermod" command works just like "pure-pw useradd" except that
it modifies an existing account instead of creating a new one.

For instance, we will add a quota to Joe. Joe should be limited to 1000
files and 10 Megabytes.

                      pure-pw usermod joe -n 1000 -N 10

Let's have a look at /etc/pureftpd.passwd:

joe:$7$C6..../....swVShTUX9kLJepm0vvj7dUXPqtULzQ9G3GT/GAO3bd3$GMHJRyUdSRwNROunwtRbEDHlx5t3eNQew7bb1dz29K2:500:101::/home/ftpusers/joe/./::::::1000:10485760::::::

As you can see, the size quota is stored in bytes in the file.


   ------------------------ RESETTING ATTRIBUTES ------------------------


To disable file quotas, use pure-pw usermod <user> -n ''
To disable size quotas, use pure-pw usermod <user> -N ''
To disable ratios, use pure-pw usermod <user> -q '' -Q ''
To disable download bandwidth throttling, use pure-pw usermod <user> -t ''
To disable upload bandwidth throttling, use pure-pw usermod <user> -T ''
To disable IP filtering, use pure-pw usermod <user> <-i,-I,-r or -R> ''
To disable time restrictions, use pure-pw usermod <user> -z ''
To disable the number of concurrent sessions, use pure-pw usermod <user> -y ''


      ------------------------ DELETING USERS ------------------------


We won't delete Joe at this time. Joe is a fine guy :) But FYI, deleting an
user is as simple as running "pure-pw userdel", whose syntax is:

         pure-pw userdel <login> [-f <passwd file>] [-m]
         
Deleting Joe would be:

                             pure-pw userdel joe
                             
The content of his home directory is kept. Delete it by hand if you want.


    ------------------------ CHANGING PASSWORDS ------------------------


To change the password of a user, use "pure-pw passwd":

         pure-pw passwd <login> [-f <passwd file>] [-m]


      ------------------------ DISPLAYING INFO ------------------------
      

To review info about one user, reading the /etc/pureftpd.passwd file is ok,
but it's not really human-friendly.

It's why you can use "pure-pw show", whose syntax is:

         pure-pw show    <login> [-f <passwd file>]
         
Let's try with joe:

                              pure-pw show joe
                              

Login              : joe
Password           : $7$C6..../....swVShTUX9kLJepm0vvj7dUXPqtULzQ9G3GT/GAO3bd3$GMHJRyUdSRwNROunwtRbEDHlx5t3eNQew7bb1dz29K2
UID                : 500 (ftpuser)
GID                : 101 (ftpgroup)
Directory          : /home/ftpusers/joe/./
Full name          : 
Download bandwidth : 0 Kb (unlimited)
Upload   bandwidth : 0 Kb (unlimited)
Max files          : 1000 (enabled)
Max size           : 10 Mb (enabled)
Ratio              : 0:0 (unlimited:unlimited)
Allowed local  IPs : 
Denied  local  IPs : 
Allowed client IPs : 192.168.0.0/16
Denied  client IPs : 192.168.1.1,blah.verybadhost.com
Time restrictions  : 0900-1800 (enabled)
Max sim sessions   : 0 (unlimited)


  "/./" at the end of a home directory means that this user will be chrooted.


     ------------------------ COMMITTING CHANGES ------------------------
      

IMPORTANT:

You can add, modify and delete users with the previous commands, or by
editing /etc/pureftpd.passwd by hand. But the FTP server won't consider the
changes you make to that file, until you commit them.

Committing changes really means that a new file is created from
/etc/pureftpd.passwd (or whatever file name you choose) . That new file is a
PureDB file. It contains exactly the same info than the other file. But in
that file, accounts are sorted and indexed for faster access, even with
thousands of accounts. PureDB files are binary files, don't try to view them
or your terminal will beep like hell.

Let's create a PureDB file from /etc/pureftpd.passwd. The indexed file will
be called /etc/pureftpd.pdb (as always, choose whatever name you like):

                                pure-pw mkdb
                        
this reads /etc/pureftpd.passwd and creates /etc/pureftpd.pdb by default, but
to read another file, add the pdb file, optionnaly followed by -f <passwd file>

For instance:

  pure-pw mkdb /etc/accounts/myaccounts.pdb -f /etc/accounts/myaccounts.txt

All modifications you made to the virtual users database will be committed
automatically: all new accounts will be activated at the same time and all
deleted users won't be able to log in as soon as you'll have hit the Return
key.

There's no need to restart the pure-ftpd server to commit changes.

You can also change something to the text passwords file (add users, change
password, delete users, etc) and automatically run 
"pure-pw mkdb /etc/pureftpd.pdb" afterwards. To do so, just use the -m
switch:

pure-pw passwd joe -m

This command will change Joe's password in pureftpd.passwd *and* commit the
change to /etc/pureftpd.pwd .


  ------------------------ ENABLING VIRTUAL USERS ------------------------
  
  
Of course, to use virtual users, you have to enable their support in the FTP
server itself. At compile-time, this is done by giving --with-puredb to
./configure (--with-everything also enables it and binary packages have it
compiled in) .

Then, add this switch to your usual pure-ftpd switches:

-l puredb:/path/to/puredb_file

If long options are enabled, you can also use --login instead of -l .

Let's run the server with automatic creation of home directories and puredb
authentication:

/usr/local/sbin/pure-ftpd -j -lpuredb:/etc/pureftpd.pdb &

Try to 'ftp localhost' and log in as joe.


------------------------ CONVERTING SYSTEM ACCOUNTS ------------------------
  
  
You can convert all system (/etc/passwd) accounts to virtual FTP users, with
the "pure-pwconvert" tool.

Just run it:

                    pure-pwconvert >> /etc/pureftpd.passwd


If you do it as a non-privileged user, passwords won't be filled in. If you
do it as root, everything will be copied, even hashed passwords.

Copying system accounts to FTP accounts makes sense, because that way, users
can use different passwords for FTP and for Telnet access.


  ------------------------ ENVIRONNEMENT VARIABLES ------------------------
  
  
If defined, a PURE_PASSWDFILE environment variable can set the default path
to the pureftpd.passwd file. Without this variable, it defaults to
/etc/pureftpd.passwd .  
  
If defined, a PURE_DBFILE environment variable can set the default path
to the pureftpd.pdb file. Without this variable, it defaults to
/etc/pureftpd.pdb .