File: README.Virtual-Users

package info (click to toggle)
pure-ftpd 1.0.47-3
  • links: PTS
  • area: main
  • in suites: buster
  • size: 3,212 kB
  • sloc: ansic: 29,132; sh: 1,632; makefile: 500; perl: 280
file content (316 lines) | stat: -rw-r--r-- 11,951 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316


       ------------------------ 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: 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.


       ------------------------ 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 .