1 bftpd documentation
2 originally written by Max-Wilhelm Bruker <brukie@gmx.net>
3 currently maintained by Jesse Smith <jessefrgsmith@yahoo.ca>
4
5
6 This document is the documentation for the bftpd FTP server.
7 ______________________________________________________________________
8
9 Table of Contents
10
11
12 1. Introduction
13 2. Installation
14 2.1 Compiling
15 2.2 Running the server
16
17 3. Configuration
18 3.1 User management
19 3.2 The configuration file
20 3.2.1 The global structure
21 3.2.2 User structures
22 3.2.3 Group structures
23 3.2.4 Directory structures
24
25 4. FAQ
26 4.1 Problems while compiling
27 4.1.1 I can't compile bftpd
28 4.1.2 There are strange warnings
29 4.1.3 Make tells me I can't use wtmp
30 4.2 Problems when trying to run it
31 4.2.1 I get a warning like "Could not get peer IP address."
32 4.2.2 I get an error like "Bind failed: Address already in use."
33 4.3 Problems during the FTP sessions
34 4.3.1 I get an error like "500 Unknown command: 'foo'"
35 4.3.2 The session terminates with a 421 error
36 4.4 Miscellaneous
37 4.4.1 How does the on-the-fly compression work?
38 4.4.2 My options for an anonymous user don't work
39 4.4.3 Why is there so little documentation?
40 4.5 Logging
41 4.5.1 What information is logged?
42 4.5.2 How can I get bandwidth usage information?
43
44
45 5. Credits
46 5.1 Portability testing
47 5.2 Suggestions, bug reports & code contributions
48 5.3 Documentation contributions
49 5.4 Others
50
51
52 ______________________________________________________________________
53
54 1. Introduction
55
56 bftpd is an FTP server for Linux, BSD/OS, FreeBSD, Solaris, DG-UX and
57 Tru64. (I don't know if it runs on other systems, please mail me if
58 you have tried it). It runs either with inetd or standalone.
59
60 It tries to be very configurable while being fast and small. You can
61 make defaults for each configuration option, and then override these
62 defaults in user-specific and directory-specific structures.
63
64 Features of bftpd include:
65
66 +o Easy configuration
67
68 +o Speed
69
70 +o Support for most RFC FTP commands
71
72 +o tar.gz on-the-fly compression/archiving
73
74 +o Security with chroot without special setup
75
76 +o No need for files (sh, ls...) in a chroot environment
77
78 +o Logging to wtmp and to a logfile or syslog
79
80 +o PAM and passwd/shadow support
81
82 +o Support for SITE CHOWN/CHMOD
83
84 2. Installation
85
86 2.1. Compiling
87
88 First execute the following commands (replacing x.x.x by the version
89 number you are installing):
90
91
92 tar xzf bftpd-x.x.x.tar.gz
93 cd bftpd-x.x.x
94 ./configure
95 make
96 make install
97
98
99
100 Note that you have to copy bftpd.conf from the source directory to
101 /etc manually if you are upgrading from a previous version, as 'make
102 install' does not overwrite your existing configuration.
103
104 Note: If you want to use the 'tar.gz on-the-fly' feature of bftpd, you
105 must grab the source code of the program "pax" and extract it into a
106 subdirectory of the bftpd source directory. Then, instead of doing
107 "./configure", do "./configure --enable-pax=pax-sourcedir --enable-
108 libz". You must also have the library libz and its header file,
109 /usr/include/zlib.h.
110
111 2.2. Running the server
112
113 bftpd runs in either standalone or inetd mode.
114
115 If you want inetd mode
116 Add the following to your /etc/inetd.conf:
117
118
119 ftp stream tcp nowait root /usr/sbin/bftpd bftpd
120
121
122
123 Give inetd a HUP or reboot your system. Your FTP server should work
124 now.
125
126 If you want inetd mode with xinetd
127 Add the following to your /etc/xinetd.conf:
128
129
130
131 service ftp
132 {
133 disable = no
134 socket_type = stream
135 wait = no
136 user = root
137 server = /usr/sbin/bftpd
138 log_on_success += HOST PID
139 log_on_failure += HOST
140 nice = 10
141 }
142
143
144
145 (contributed by JackRipper)
146
147 If you want standalone mode:
148 Make the OS execute
149
150
151 /usr/sbin/bftpd -d
152
153
154
155 at bootup.
156
157 3. Configuration
158
159 3.1. User management
160
161 You can manage the users simply by editing /etc/passwd and, if your
162 system supports it, /etc/shadow. Any user existent in /etc/passwd can
163 connect to the FTP server if he has a usable password and meets
164 certain configurable criteria. Having anonymous users is possible by
165 setting a configuration variable called ANONYMOUS_USER to yes. PAM is
166 also supported.
167
168 3.2. The configuration file
169
170 3.2.1. The global structure
171
172 In the "global" structure, you can assign values to configuration
173 options. The syntax is like the following:
174
175
176 global {
177 name1="value1"
178 name2="value2"
179 }
180
181
182
183 3.2.2. User structures
184
185 There are also user structures, in which you can override the global
186 settings for particular users. Example:
187
188
189
190 global {
191 name1="value1"
192 name2="value2"
193 }
194 user foo {
195 name1="value3"
196 }
197
198
199
200 If the user foo is logged in, name1 will be value3. If another user is
201 logged in, name1 will be value1. name2 is always value2.
202
203 3.2.3. Group structures
204
205 You can also define options for groups of users. It is just as it
206 would be for one user, but you can put more than one user in a group.
207 You can also put system groups into them by using the @ character.
208 Example:
209
210
211 group foo,bar,@baz {
212 name1="value1"
213 }
214
215
216
217 This options affect the users foo and bar and every user who is in the
218 system group baz. A supplementary membership is sufficient.
219
220 3.2.4. Directory structures
221
222 You can set options which affects only the users who are in a certain
223 directory, or in any subdirectory of it, recursively. Note that you
224 must put these structures 4minside24m the global, user and group
225 structures. This way, you can also override directory-specific
226 settings for particular users. Example:
227
228
229 global {
230 name1="value1"
231 directory "/foo" {
232 name1="value2"
233 }
234 }
235 user bar {
236 directory "/foo" {
237 name1="value3"
238 }
239 }
240
241
242
243 In this example, name1 will be value3 if the user bar is in the direc-
244 tory /foo. It will be value2 if another user is in the directory /foo.
245 In any other case, it will be value1.
246
247 An explanation of the name/value pairs is in the example configuration
248 file supplied with bftpd (if you are not upgrading, this file has
249 already been copied to /etc on your system). Modify it so that it fits
250 your needs. The defaults should be OK though.
251
252
253 4. FAQ
254
255 4.1. Problems while compiling
256
257 4.1.1. I can't compile bftpd
258
259 Let me know. Please tell me what architecture and operating system you
260 are using, and give me the output of the complete compilation process
261 (configure and make). I don't get a lot of mail, so I'll try to answer
262 your questions. If I don't reply, I have almost certainly forgotten
263 your mail, so please send it again :)
264
265 4.1.2. There are strange warnings
266
267 It is likely that compiling bftpd on a platform I haven't tested may
268 give you some warnings. Even if it compiles successfully and runs
269 without crashing, please tell me, as compiler warnings 4mcan24m cause
270 problems which are not obvious.
271
272 4.1.3. Make tells me I can't use wtmp
273
274 You are probably running Solaris. As I don't have access to a Solaris
275 computer, I have never been able to test the wtmp functions in it. If
276 you get a warning like this and you don't know what wtmp is, just
277 don't worry about it, or else help me to fix the error.
278
279 4.2. Problems when trying to run it
280
281 4.2.1. I get a warning like "Could not get peer IP address."
282
283 You have started bftpd on the console. If you want to run it as a
284 standalone server, you have to invoke it with the "-d" option. If you
285 have set it up as an inetd server, you can test it with:
286
287
288 hostname:~$ ftp localhost
289
290
291
292 4.2.2. I get an error like "Bind failed: Address already in use."
293
294 This error means that another process has bound itself to the port you
295 want to run bftpd on. You can set this port in bftpd.conf with the
296 option PORT in the global structure. It defaults to 21. If you have
297 not changed that, you probably forgot to turn off your old FTP server.
298 Look in /etc/inetd.conf and in "ps auxwww | grep ftp".
299
300 4.3. Problems during the FTP sessions
301
302 4.3.1. I get an error like "500 Unknown command: 'foo'"
303
304 Your client has sent a command to the server which it didn't
305 understand. This is my fault, unless you have written a really
306 inexistent command. Please check your command for typographic errors
307 and report the error to me if you are sure that the command was right.
308
309 4.3.2. The session terminates with a 421 error
310
311 If you try to log in with a wrong password, bftpd will terminate the
312 connection. If you already had logged in before the error appeared, or
313 the error appeared before you could log in, it definitely is a bug.
314 Please tell me everything about it.
315
316
317
318 4.4. Miscellaneous
319
320 4.4.1. How does the on-the-fly compression work?
321
322 Let's say you have a directory called foo. Even if there is no file
323 called foo.tar.gz, you can RETR this file over FTP and it will contain
324 the contents of the directory foo, tar-gzipped. You can also RETR the
325 following files:
326
327 +o dirname.tar
328
329 +o filename.gz
330
331 If you want to use this, you must compile it in (see the
332 installation section).
333
334 4.4.2. My options for an anonymous user don't work
335
336 If you have a structure with an ALIAS=... in it, you mustn't put any
337 more options in it. Instead, put them into the structure the alias
338 points to.
339
340 4.4.3. Why is there so little documentation?
341
342 The answer is simple, nobody has written anything
343 I never know what to write, so if you have any idea of how to improve
344 the documentation, please tell me. The same applies to translations of
345 documentation. If you want to contribute something, write it out and
346 e-mail it to me.
347
348
349 4.5.1. What information is logged?
350
351 By default, information is logged to /var/log/bftpd.log. This file contains
352 records of failed logins and successful logins, including the client's IP
353 address and username. Session timeouts are logged, as are file uploads and
354 downloads. Sessions where the client decides to quit are also logged.
355 Each log entry includes the time, date and process ID of the server to
356 help you track down problems.
357
358
359 4.5.2. How can I get bandwidth usage information?
360
361 As of bftpd version 2.5, the server has the option of logging bandwidth usage.
362 To use this feature, set the option BANDWIDTH in bftpd.conf to point to a valid
363 directory on the server. By default, bandwidth usage is not logged.
364 After each file transfer (upload or download) the server will save the amount of
365 data transferred in a log file. Let's say you set the BANDWIDTH variable to point to "/var/log/bftpd",
366 the server will keep a log of transfers in a file for each day. So if the client
367 connects on December 20, 2009, the file will be called /var/log/bftpd/2009-12-20.txt.
368 If another client connects on December 21, 2009, the file will be called /var/log/bftpd/2009-12-21.txt.
369 Now, how do you make use of that data?
370 Let's say you want to get bandwidth usage for everyone for Dec 20, 2009. You could use
371 this command:
372
373 cat /var/log/bftpd/2009-12-20.txt | awk 'BEGIN {down=0; up=0} {down = down + $2; up = up + $3} END {print "Download: " down " -- Uploaded: " up}'
374
375 But if you wanted to get usage information for just one user, you could do this:
376
377 cat /var/log/bftpd/2009-12-20.txt | grep myusername | awk 'BEGIN {down=0; up=0} {down = down + $2; up= up + $3} END {print "Download: " down " -- Uploaded: " up}'
378
379 To get the usage information for one user for the month of December, you could use:
380
381 cat /var/log/bftpd/2009-12-* | grep myusername | awk 'BEGIN {down=0; up=0} {down = down + $2; up= up + $3} END {print "Download: " down " -- Uploaded: " up}'
382
383
384 Please note that the bandwidth usage logs should be rotated just like any other log to avoid filling up the server's disk.
385
386
387
388
389 5. Credits
390
391 5.1. Portability testing
392
393
394 +o David L. Nicol (david@kasey.umkc.edu) tested bftpd on Tru64.
395
396 +o JackRipper (vic@altoona.net) tested bftpd on BSD/OS and DG-UX.
397
398 +o Christian Beyerlein (christian@beyerlein.de) tested bftpd on
399 FreeBSD and Solaris.
400
401 +o The people from #linux (IRCNet) tested bftpd on various operating
402 systems.
403
404 5.2. Suggestions, bug reports & code contributions
405
406
407 +o Josh Woodcock (josh@hamparts.com) gave some hints about Solaris 8.
408
409 +o Floh (floh@maflohsoft.de) suggested the ASCII mode support.
410
411 +o Erik Hensema (erik@hensema.xs4all.nl) found a Linux 2.4.0 netfilter
412 bug which affected bftpd.
413
414 +o Heiko Rother (rother@cmsnet.de) suggested a lot of things (see
415 changelog).
416
417 +o Christophe Bailleux (cb@grolier.fr) loves to find problems in the
418 directory listing routines. He also suggested a lot of things and
419 contributed some code.
420
421 +o Jonathan Heusser (jonathanheusser@gyml.unibas.ch) found a buffer
422 overflow bug.
423
424
425 +o Christian Beyerlein (christian@beyerlein.de) suggested to make user
426 aliases.
427
428 +o Elmusafir (jslmarti@campus.cem.itesm.mx) reported the StarOffice
429 problem fixed in 1.0.8.
430
431 +o Alex Madden (alexm@immstudios.com) and Daniel Mack
432 (daniel.mack@nextra.de) reported the Solaris incompatibility fixed
433 in 1.0.8.
434
435 +o Daniel Mack (daniel.mack@nextra.de) contributed a big patch (see
436 changelog).
437
438 5.3. Documentation contributions
439
440
441 +o Radek Michalski (radek@end.p-s.com.pl) translates the bftpd docs
442 into Polish and also contributes new text.
443
444 5.4. Others
445
446
447 +o Some ideas about code structure and portability where taken from
448 betaftpd bei Steinar H. Gunderson. But these were only a few lines!
449
450
451
452