1<!doctype linuxdoc system> 2 3<article> 4 5<!-- Title information --> 6 7<title>bftpd documentation</title> 8<author> 9 <name>written by Max-Wilhelm Bruker <tt/<brukie@gmx.net/></name> 10</author> 11<!--<date>$Id: bftpddoc-en.sgml,v 1.1 2007/04/16 12:02:21 mutalis Exp $</date>--> 12 13<abstract> 14This document is the documentation for the bftpd FTP server. 15</abstract> 16 17<!-- Table of contents --> 18<toc> 19 20<!-- Begin the document --> 21 22<sect>Introduction 23 <p> 24bftpd is an FTP server for Linux, BSD/OS, FreeBSD, Solaris, DG-UX and Tru64. (I don't know if it runs on other systems, please mail me if you have tried it). It runs either with inetd or standalone. 25 </p> 26 <p> 27 It tries to be very configurable while being fast and small. You can make defaults for each configuration option, and then override these defaults in user-specific and directory-specific structures. 28 </p> 29 <p> 30Features of bftpd include: 31 <itemize> 32<item>Easy configuration 33<item>Speed 34<item>Support for most RFC FTP commands 35<item>tar.gz on-the-fly compression/archiving 36<item>Security with chroot without special setup 37<item>No need for files (sh, ls...) in a chroot environment 38<item>Logging to wtmp and to a logfile or syslog 39<item>PAM and passwd/shadow support 40<item>Support for SITE CHOWN/CHMOD 41 </itemize> 42 </p> 43</sect> 44 45<sect>Installation 46<sect1>Compiling 47 <p> 48First execute the following commands (replacing x.x.x by the version number you are installing): 49 <tscreen><verb> 50tar xzf bftpd-x.x.x.tar.gz 51cd bftpd-x.x.x 52./configure 53make 54make install 55 </verb></tscreen> 56Note that you have to copy bftpd.conf from the source directory to /etc manually if you are upgrading from a previous version, as 'make install' does not overwrite your existing configuration. 57 </p> 58 <p> 59 Note: If you want to use the 'tar.gz on-the-fly' feature of bftpd, you must 60 grab the source code of the program "pax" and extract it into 61 a subdirectory of the bftpd source directory. Then, instead of doing 62 "./configure", do "./configure --enable-pax=pax-sourcedir --enable-libz". 63 You must also have the library libz and its header file, /usr/include/zlib.h. 64 </p> 65<sect1>Running the server 66<p> 67bftpd runs in either standalone or inetd mode. 68 <descrip> 69<tag>If you want inetd mode</tag> 70 Add the following to your /etc/inetd.conf: 71<tscreen><verb>ftp stream tcp nowait root /usr/sbin/bftpd bftpd</verb></tscreen> 72 Give inetd a HUP or reboot your system. Your FTP server 73 should work now. 74<tag>If you want inetd mode with xinetd</tag> 75 Add the following to your /etc/xinetd.conf: 76<tscreen><verb> 77service ftp 78{ 79 disable = no 80 socket_type = stream 81 wait = no 82 user = root 83 server = /usr/sbin/bftpd 84 log_on_success += DURATION USERID 85 log_on_failure += USERID 86 nice = 10 87} 88</verb></tscreen> 89(contributed by JackRipper) 90<tag>If you want standalone mode:</tag> 91 Make the OS execute 92 <tscreen><verb>/usr/sbin/bftpd -d</verb></tscreen> 93 at bootup. 94 </descrip> 95 </p> 96 97<sect>Configuration 98<sect1>User management 99<p> 100You can manage the users simply by editing /etc/passwd and, if your system supports it, /etc/shadow. Any user existent in /etc/passwd can connect to the FTP server if he has a usable password and meets certain configurable criteria. Having anonymous users is possible by setting a configuration variable called ANONYMOUS_USER to yes. PAM is also supported. 101</p> 102<sect1>The configuration file 103<sect2>The global structure 104<p> 105In the &dquot;global&dquot; structure, you can assign values to configuration options. The syntax is like the following: 106<tscreen><verb> 107global { 108 name1="value1" 109 name2="value2" 110} 111</verb></tscreen> 112</p> 113<sect2>User structures 114<p> 115There are also user structures, in which you can override the global settings for particular users. Example: 116<tscreen><verb> 117global { 118 name1="value1" 119 name2="value2" 120} 121user foo { 122 name1="value3" 123} 124</verb></tscreen> 125If the user foo is logged in, name1 will be value3. If another user is logged in, name1 will be value1. name2 is always value2. 126</p> 127<sect2>Group structures 128<p> 129You can also define options for groups of users. It is just as it would be for one user, but you can put more than one user in a group. You can also put system groups into them by using the @ character. Example: 130<tscreen><verb> 131group foo,bar,@baz { 132 name1="value1" 133} 134</verb></tscreen> 135This options affect the users foo and bar and every user who is in the system group baz. A supplementary membership is sufficient. 136</p> 137<sect2>Directory structures 138<p> 139You can set options which affects only the users who are in a certain directory, or in any subdirectory of it, recursively. Note that you must put these structures <em>inside</em> the global, user and group structures. This way, you can also override directory-specific settings for particular users. Example: 140<tscreen><verb> 141global { 142 name1="value1" 143 directory "/foo" { 144 name1="value2" 145 } 146} 147user bar { 148 directory "/foo" { 149 name1="value3" 150 } 151} 152</verb></tscreen> 153In this example, name1 will be value3 if the user bar is in the directory /foo. It will be value2 if another user is in the directory /foo. In any other case, it will be value1. 154</p> 155<p> 156An explanation of the name/value pairs is in the example configuration file supplied with bftpd (if you are not upgrading, this file has already been copied to /etc on your system). Modify it so that it fits your needs. The defaults should be OK though. 157</p> 158 159<sect>FAQ 160<sect1>Problems while compiling 161<sect2>I can't compile bftpd 162<p> 163Let me know. Please tell me what architecture and operating system you are using, and give me the output of the complete compilation process (configure and make). I don't get a lot of mail, so I'll try to answer your questions. If I don't reply, I have almost certainly forgotten your mail, so please send it again :) 164</p> 165<sect2>There are strange warnings 166<p> 167It is likely that compiling bftpd on a platform I haven't tested may give you some warnings. Even if it compiles successfully and runs without crashing, please tell me, as compiler warnings <em>can</em> cause problems which are not obvious. 168</p> 169<sect2>Make tells me I can't use wtmp 170<p> 171You are probably running Solaris. As I don't have access to a Solaris computer, I have never been able to test the wtmp functions in it. If you get a warning like this and you don't know what wtmp is, just don't care, else help me to fix the error. 172</p> 173<sect1>Problems when trying to run it 174<sect2>I get a warning like &dquot;Could not get peer IP address.&dquot; 175<p> 176You have started bftpd on the console. If you want to run it as a standalone server, you have to invoke it with the &dquot;-d&dquot; option. If you have set it up as an inetd server, you can test it with: 177<tscreen><verb> 178hostname:˜$ ftp localhost 179</verb></tscreen> 180</p> 181<sect2>I get an error like &dquot;Bind failed: Address already in use.&dquot; 182<p> 183This error means that another process has bound itself to the port you want to run bftpd on. You can set this port in bftpd.conf with the option PORT in the global structure. It defaults to 21. If you have not changed that, you probably forgot to turn off your old FTP server. Look in /etc/inetd.conf and in &dquot;ps auxwww | grep ftp&dquot;. 184</p> 185<sect1>Problems during the FTP sessions 186<sect2>I get an error like &dquot;500 Unknown command: 'foo'&dquot; 187<p> 188Your client has sent a command to the server which it didn't understand. This is my fault, unless you have written a really inexistent command. Please check your command for typographic errors and report the error to me if you are sure that the command was right. 189</p> 190<sect2>The session terminates with a 421 error 191<p> 192If you try to log in with a wrong password, bftpd will terminate the connection. If you already had logged in before the error appeared, or the error appeared before you could log in, it definitely is a bug. Please tell me everything about it. 193</p> 194<sect1>Miscellaneous 195<sect2>How does the on-the-fly compression work? 196<p> 197Let's say you have a directory called foo. Even if there is no file called foo.tar.gz, you can RETR this file over FTP and it will contain the contents of the directory foo, tar-gzipped. You can also RETR the following files: 198<itemize> 199<item>dirname.tar</item> 200<item>filename.gz</item> 201</itemize> 202If you want to use this, you must compile it in (see the installation section). 203</p> 204<sect2>My options for an anonymous user don't work 205<p> 206If you have a structure with an ALIAS=... in it, you mustn't put any more options in it. Instead, put them into the structure the alias points to. 207</p> 208<sect2>Why is there so little documentation? 209<p> 210The answer is simple, nobody has written anything :)<newline> 211I never know what to write, so if you have any idea of how to improve the documentation, please tell me. The same applies to translations of documentation. If you want to contribute something, just do it, but <em>please</em> care about typographic errors and grammar. 212</p> 213<sect>Credits 214<sect1>Portability testing 215<p> 216<itemize> 217<item>David L. Nicol (david@kasey.umkc.edu) tested bftpd on Tru64.</item> 218<item>JackRipper (vic@altoona.net) tested bftpd on BSD/OS and DG-UX.</item> 219<item>Christian Beyerlein (christian@beyerlein.de) tested bftpd on FreeBSD and Solaris.</item> 220<item>The people from #linux (IRCNet) tested bftpd on various operating systems.</item> 221</itemize> 222</p> 223<sect1>Suggestions, bug reports & code contributions 224<p> 225<itemize> 226<item>Josh Woodcock (josh@hamparts.com) gave some hints about Solaris 8.</item> 227<item>Floh (floh@maflohsoft.de) suggested the ASCII mode support.</item> 228<item>Erik Hensema (erik@hensema.xs4all.nl) found a Linux 2.4.0 netfilter bug which affected bftpd.</item> 229<item>Heiko Rother (rother@cmsnet.de) suggested a lot of things (see changelog).</item> 230<item>Christophe Bailleux (cb@grolier.fr) loves to find problems in the directory listing routines. He also suggested a lot of things and contributed some code.</item> 231<item>Jonathan Heusser (jonathanheusser@gyml.unibas.ch) found a buffer overflow bug.</item> 232<item>Christian Beyerlein (christian@beyerlein.de) suggested to make user aliases.</item> 233<item>Elmusafir (jslmarti@campus.cem.itesm.mx) reported the StarOffice problem fixed in 1.0.8.</item> 234<item>Alex Madden (alexm@immstudios.com) and Daniel Mack (daniel.mack@nextra.de) reported the Solaris imcompatibility fixed in 1.0.8.</item> 235<item>Daniel Mack (daniel.mack@nextra.de) contributed a big patch (see changelog).</item> 236</itemize> 237</p> 238<sect1>Documentation contributions 239<p> 240<itemize> 241<item>Radek Michalski (radek@end.p-s.com.pl) translates the bftpd docs into Polish and also contributes new text.</item> 242</itemize> 243</p> 244<sect1>Others 245<p> 246<itemize> 247<item>Some ideas about code structure and portability where taken from betaftpd bei Steinar H. Gunderson. But these were only a few lines! 248</itemize> 249</p> 250</article> 251