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