Edit File: 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 . They are crypto hashed with blowfish, md5, multiple-des and simple des, in this order, according to what your system has support fort. ------------------------ 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 host>[/<mask>][,<allow client host>[/<mask>]]...] [-R <deny client host>[/<mask>][,<deny client host>[/<mask>]]...] [-i <allow local host>[/<mask>][,<allow client host>[/<mask>]]...] [-I <deny local host>[/<mask>][,<deny local host>[/<mask>]]...] [-y <max number of concurrent sessions>] [-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: argon2i, scrypt, bcrypt, SHA-512, MD5. Argon2i and scrypt are the recommended functions, and require pure-ftpd to be compiled in presence of libsodium. ------------------------ 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. ------------------------ COMMITING 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. Commiting 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 atomatically: 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 .