<?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [ <!ENTITY kappname "&kwuftpd;"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE" > <!-- change language only here --> ]> <book lang="&language;"> <bookinfo> <title>The &kwuftpd; Handbook</title> <authorgroup> <author> <firstname>Jonathan</firstname> <surname>Singer</surname> <affiliation> <address><email>jsinger@genome.wi.mit.edu</email></address> </affiliation> </author> <othercredit role="developer"> <firstname>Bernhard</firstname> <surname>Rosenkraenzer</surname> <affiliation> <address><email>bero@redhat.com</email></address> </affiliation> <contrib>Developer</contrib> </othercredit> <othercredit role="reviewer"> <firstname>Lauri</firstname> <surname>Watts</surname> <affiliation> <address><email>lauri@kde.org</email></address> </affiliation> <contrib>Reviewer</contrib> </othercredit> <!-- TRANS:ROLES_OF_TRANSLATORS --> </authorgroup> <copyright> <year>2000</year> <holder>Jonathan Singer</holder> </copyright> <legalnotice>&FDLNotice;</legalnotice> <date>2000-12-14</date> <releaseinfo>0.02.00</releaseinfo> <abstract><para>&kwuftpd; is a &kde; front-end to editing <application>wu-ftpd</application>'s <filename>ftpaccess</filename> files.</para></abstract> <keywordset> <keyword>KDE</keyword> <keyword>kwuftpd</keyword> <keyword>kdeadmin</keyword> <keyword>ftp</keyword> <keyword>server</keyword> <keyword>configuration</keyword> </keywordset> </bookinfo> <chapter id="introduction"> <title>Introduction</title> <para>&UNIX; operating systems are perhaps best known for their role in running servers. It can be difficult, however, for users to configure the files necessary to manage those services. At the same time, many distributors overcompensate for that difficulty by shipping systems that default to dangerously open configurations.</para> <para>&kwuftpd; is a &kde; front-end to editing <application>wu-ftpd</application>'s ftpaccess files. &kwuftpd; was originally written for <application>BeroFTPD</application> 1.2.1 and has been adapted to the version of <application>wu-ftpd</application> 2.6.1 found in &RedHat; &Linux; 7.0. If you are using a newer version of <application>wu-ftpd</application> with more features, you'll have to update your &kwuftpd; (or edit <filename>ftpaccess</filename> by hand) to make use of them.</para> <warning><para>&kwuftpd; is still beta; you should make a backup copy of your ftpaccess file before editing it with &kwuftpd;.</para></warning> <para>&kwuftpd; was written by Bernhard Rosenkraenzer <email>bero@redhat.com</email> and is (c) 2000 &RedHat;, Inc.</para> <sect1 id="disclaimer"> <title>Disclaimers</title> <para>Beyond the usual disclaimers that come with software (<quote>We take no responsibility for anything bad that might happen.</quote>), it should be pointed out that &kwuftpd; controls the ability of users to connect to your system and add, delete and modify files. Some things to keep in mind:</para> <itemizedlist> <listitem><para>&kwuftpd; makes it easier to establish a secure server -- it does not guarantee it. There is a wealth of books, web sites and courses on network security and administrators should take advantage of them.</para></listitem> <listitem><para>Examples given in this documentation are intended to show the operation of &kwuftpd;. They are not security recommendations and should not be treated as such.</para></listitem> <listitem><para>Be sure to back up the <filename>/etc/ftpaccess</filename> file before modifying it with &kwuftpd;.</para></listitem> </itemizedlist> </sect1> </chapter> <chapter id="basic-ftp-setup"> <title>Basic &FTP; setup</title> <para>&kwuftpd; is only valuable on a system with a working &FTP; server. Setting up a server is beyond the scope of this document, but in a nutshell:</para> <procedure> <step><para><application>wu-ftpd</application> or a similar &FTP; server must be installed. The <application>anonftp</application> package can also be helpful to enable anonymous &FTP;.</para></step> <step><para>The <filename>/etc/inetd.conf</filename> file should contain a line like:</para> <screen># ftp stream tcp nowait root /usr/sbin/tcpd in.ftpd -l -a</screen> <para>Uncomment the line by removing the # from the start of the line. If your system shipped with the line uncommented, treat it as a warning sign and comment out other services that you do not want. Restart <filename>/etc/inetd.conf</filename>. (Entering <userinput><command>/etc/rc.d/init.d/inet</command> <parameter>restart</parameter></userinput> at the command-line works on &RedHat; and similar systems.) </para></step> </procedure> </chapter> <chapter id="using-kwuftpd"> <title>Using &kwuftpd;</title> <sect1 id="starting-kwuftpd"> <title>Starting &kwuftpd;</title> <para>To launch &kwuftpd;, select <menuchoice><guisubmenu>System</guisubmenu> <guimenuitem>FTPD Editor</guimenuitem></menuchoice> from the &kde; menu. Or type <userinput><command>kwuftpd</command></userinput> at the command-line. The standard &Qt; and &kde; command-line options are available, and are displayed by typing <userinput><command>kwuftpd</command> <option>--all</option></userinput>.</para> </sect1> <sect1 id="about-ftp-accounts"> <title>About &FTP; accounts</title> <para>&kwuftpd; often asks the user to distinguish between three types of users:</para> <variablelist> <varlistentry> <term>Anonymous</term> <listitem> <para>For use by anyone who can connect to the server, these users log in as <userinput>ftp</userinput> or <userinput>anonymous</userinput> and submit their email address as the password.</para> </listitem> </varlistentry> <varlistentry> <term>Guest</term> <listitem> <para>Users with &FTP; accounts in <filename>/etc/ftpusers</filename> but not full accounts on the system.</para> </listitem> </varlistentry> <varlistentry> <term>Real</term> <listitem> <para>Users with accounts on the system.</para> </listitem> </varlistentry> </variablelist> </sect1> <sect1 id="menuref"> <title>Menu Commands</title> <sect2 id="file-menu"> <title>The <guimenu>File</guimenu> menu</title> <variablelist> <varlistentry> <term><menuchoice> <guimenu><accel>F</accel>ile</guimenu> <guimenuitem><accel>L</accel>oad /etc/ftpaccess</guimenuitem> </menuchoice></term> <listitem><para>Open <filename>/etc/ftpaccess</filename>, the standard <application>wu-ftpd</application> configuration file, for editing.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>F</accel>ile</guimenu> <guimenuitem>Load <accel>o</accel>ther file</guimenuitem> </menuchoice></term> <listitem><para>Open a different file for editing. Useful if you want to experiment with a different file before committing your changes to <filename>/etc/ftpaccess</filename>.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>F</accel>ile</guimenu> <guimenuitem><accel>S</accel>ave /etc/ftpaccess</guimenuitem> </menuchoice></term> <listitem><para><action>Save changes</action> to <filename>/etc/ftpaccess</filename>.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>F</accel>ile</guimenu> <guimenuitem>Save <accel>o</accel>ther file</guimenuitem> </menuchoice></term> <listitem><para><action>Save changes to a file to be specified.</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>F</accel>ile</guimenu> <guimenuitem><accel>Q</accel>uit</guimenuitem> </menuchoice></term> <listitem><para><action>Close</action> &kwuftpd;.</para></listitem> </varlistentry> </variablelist> </sect2> <sect2 id="help-menu"> <title>The <guimenu>Help</guimenu> menu</title> <variablelist> <varlistentry> <term><menuchoice> <shortcut><keycap>F1</keycap></shortcut> <guimenu><accel>H</accel>elp</guimenu> <guimenuitem><accel>C</accel>ontents...</guimenuitem> </menuchoice></term> <listitem><para><action>Open this document.</action></para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <shortcut><keycombo action="simul"> &Shift;<keycap>F1</keycap> </keycombo></shortcut> <guimenu><accel>H</accel>elp</guimenu> <guimenuitem>What's <accel>T</accel>his</guimenuitem> </menuchoice></term> <listitem><para>Select this command and then click on an item to learn more about it. &kwuftpd; has very extensive <guimenuitem>What's This</guimenuitem> documentation.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>H</accel>elp</guimenu> <guimenuitem><accel>R</accel>eport Bug...</guimenuitem> </menuchoice></term> <listitem><para>Open a convenient dialog for reporting bugs in &kwuftpd;.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>H</accel>elp</guimenu> <guimenuitem><accel>A</accel>bout KWuFTPd...</guimenuitem> </menuchoice></term> <listitem><para>Provides information about &kwuftpd;.</para></listitem> </varlistentry> <varlistentry> <term><menuchoice> <guimenu><accel>H</accel>elp</guimenu> <guimenuitem>About <accel>K</accel>DE...</guimenuitem> </menuchoice></term> <listitem><para>Provides information about the KDE project.</para></listitem> </varlistentry> </variablelist> </sect2> </sect1> <sect1 id="user-classes"> <title><guilabel>User Classes</guilabel></title> <screenshot> <screeninfo>The <guilabel>User Classes</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="user_classes.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>User Classes</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>User Classes</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to create user classes for certain <acronym>IP</acronym> addresses or blocks of addresses and to control the privileges of those classes. For example, this enables you to allow anonymous or guest users greater than normal permissions when they log in from certain machines.</para> <para>To create a new class, hit the <guibutton>Add Class</guibutton> button and, in the resulting dialog box, enter the name of the new class, the privilege levels that can belong to the class (more on this below) and the <acronym>IP</acronym> address for that class. A <userinput>*</userinput> character can be used to define a block of addresses. (For example, <userinput>127.0.0.*</userinput>includes all local users.) When done, hit <guibutton>OK</guibutton>.</para> <para>Back in the <guilabel>User Classes</guilabel> panel, you can select a class and modify its description and behavior. The <acronym>IP</acronym> address can be modified. The class can be defined to include anonymous, guest and/or real users from that address. Checking the <guilabel>Autogroup to</guilabel> box causes logins in the class to be assigned to the selected group and given its privileges.</para> <para>The right side of the panel allows classes to be assigned limits on the number of simultaneous logins during specified times. You can also specify the message to be shown when the user limit is exceeded.</para> <para>In the screenshot, real users logging in from 127.0.0.* are autogrouped to <quote>jsinger</quote> and only one user in that class is allowed at any time.</para> </sect1> <sect1 id="directories"> <title><guilabel>Directories</guilabel></title> <screenshot> <screeninfo>The <guilabel>Directories</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="directories.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Directories</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Directories</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to specify the root directory for anonymous and guest users. (Real users see the real filesystem.) It also allows you to specify the password and shadow password files to be used. If no file is specified, the system file will be used by default.</para> <para>In the screenshot, anonymous users see a filesystem rooted at <filename class="directory">/home/ftp/pub</filename>, while guest users have default access. Special &FTP; password files are used in place of the system files.</para> </sect1> <sect1 id="security"> <title><guilabel>Security</guilabel></title> <screenshot> <screeninfo>The <guilabel>Security</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="security.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Security</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Security</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to specify various security options. The <guilabel>Noretrieves</guilabel> window allows certain files or directories to be blocked from downloading. Hit the <guibutton>Add</guibutton> button and select the file to be blocked. Select an entry and hit <guibutton>Remove</guibutton> to take the file off the list.</para> <para><guilabel>Number of allowed failed logins</guilabel> causes connections to be closed after the specified number of login failures.</para> <para>Checking <guilabel>Permit SITE GROUP</guilabel> allows users to change the group they belong to with the <userinput><command>SITE</command> <option>GROUP</option></userinput> command.</para> <para>Permission to use the <command>chmod</command>, <command>delete</command>, <command>overwrite</command>, <command>rename</command> and <command>umask</command> commands can be extended or denied to anonymous, guest and/or real users.</para> <para>Anonymous users are expected to supply their email address as a password. The degree of enforcement can be controlled.</para> <variablelist> <varlistentry> <term><guilabel>No</guilabel></term> <listitem><para>There is no checking of the given password.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>trivial</guilabel></term> <listitem><para>The password must contain an @ character.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>RFC822</guilabel></term> <listitem><para>The password must be in the form of a valid address.</para></listitem> </varlistentry> </variablelist> <para>If the <guilabel>Enforce</guilabel> box is checked, logins failing the test will be denied; otherwise a warning will be issued.</para> <para>In the screenshot, the <filename class="directory">/bin</filename> and <filename class="directory">/sbin</filename> directories and the <filename>/etc/passwd</filename> file are blocked from downloads. Connections are dropped after 5 failures, <userinput><command>SITE</command> <option>GROUP</option></userinput> is forbidden, commands are forbidden to anonymous users and allowed for guest and real accounts. Anonymous users submitting non-RFC-compliant email addresses are warned.</para> </sect1> <sect1 id="messages"> <title><guilabel>Messages</guilabel></title> <screenshot> <screeninfo>The <guilabel>Messages</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="messages.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Messages</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Messages</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to specify messages to be shown to the logged-in user.</para> <para>Select a file for the banner to be displayed on connection (before login). Some extremely old &FTP; clients may be confused by a banner.</para> <para>The hostname can be specified. This will be reported to the user upon login, and can also be inserted in other messages (as <token>%L</token>). If no hostname is given, the real hostname will be used.</para> <para>Similarly, an administrator email address can be defined for insertion in messages (as <token>%E</token>).</para> <para>Check the boxes to cause messages and <filename>README</filename>s to be shown to the user every time the triggering event (explained below) occurs; otherwise they will only be shown the first time.</para> <para>Hit the <guibutton>Add Message</guibutton> button to indicate text to be displayed to the user. You will be prompted for the location of the text file, whether it will be displayed on login or on change to a specified directory and whether it will be displayed for all user classes or particular ones.</para> <para>Similarly, the user can be notified of <filename>README</filename> files upon login or change to a directory.</para> <para>In the screenshot, the text in <filename>/home/ftp/welcome.txt</filename> will be displayed on connection. The hostname <systemitem class="systemname">camelot</systemitem> and the admin address <email>jsinger@leeta.net</email> will be inserted in messages but no messages or <filename>README</filename>s have been defined yet.</para> </sect1> <sect1 id="logging"> <title><guilabel>Logging</guilabel></title> <screenshot> <screeninfo>The <guilabel>Logging</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="logging.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Logging</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Logging</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to to control what activities will be logged (to <filename>/var/log/xferlog</filename>). Anonymous, guest and real users can have different events logged, including issued commands, uploads, downloads and security violations (like login failures).</para> <para>Checking <guilabel>Redirect log to syslog</guilabel> sends the log entries to the system log instead of the &FTP; log.</para> <para>Mail can be sent to the administrator when files are uploaded. The <computeroutput>From:</computeroutput> address of the mails, the mail server and the administrator's email address can be specified.</para> <para>In the screenshot, all commands and transfers are logged, as are security violations by real users. Uploads are signalled by a message to <quote>admin</quote> from <quote>Upload Notice</quote> sent through the default mail server.</para> </sect1> <sect1 id="ratios"> <title><guilabel>Ratios</guilabel></title> <screenshot> <screeninfo>The <guilabel>Ratios</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="ratios.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Ratios</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Ratios</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to restrict the usage of anonymous and guest users. Each of these restrictions can be applied to anonymous or guest users.</para> <variablelist> <varlistentry> <term><guilabel>Upload/download ratio</guilabel></term> <listitem><para>For example, setting this to 1:5 requires users to upload 1 megabyte of data for each 5 megabytes downloaded. Setting this to an optimum value is key to your success as an aspiring w4r3z kiddi3.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Time limit</guilabel></term> <listitem><para>Allow users to connect for this amount of time.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Upload limit</guilabel></term> <listitem><para>Set the maximimum number of bytes that can be uploaded per session.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Download limit</guilabel></term> <listitem><para>Set the maximimum number of bytes that can be downloaded per session.</para></listitem> </varlistentry> </variablelist> <para>Files and directories can be exempted from upload and download limits.</para> <para>In the screenshot, ratios are off, anonymous users are allowed 15 minutes and 10 megabytes of downloads per connection.</para> </sect1> <sect1 id="uploads"> <title><guilabel>Uploads</guilabel></title> <screenshot> <screeninfo>The <guilabel>Uploads</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="uploads.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Uploads</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Uploads</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>This panel allows you to control where and how users are allowed to upload files. Hit <guibutton>Add</guibutton> to a new rule set, <guibutton>Edit</guibutton> to modify the selected set and <guibutton>Delete</guibutton> to remove the selected set.</para> <para>Each set applies to users with a specified root directory and effects a specified upload directory. The upload directory may be globbed (for example, <filename>/home/ftp/upload/*</filename> includes all contents of <filename class="directory">/home/ftp/upload</filename>).</para> <para>Uploads can be permitted or denied, and the permissions of the created files and their owner and group can be set. The ability to create new directories within the existing directory can be granted or denied.</para> </sect1> <sect1 id="virtual-hosts"> <title><guilabel>Virtual Hosts</guilabel></title> <screenshot> <screeninfo>The <guilabel>Virtual Hosts</guilabel> Panel</screeninfo> <mediaobject> <imageobject> <imagedata fileref="virtual.png" format="PNG"/> </imageobject> <textobject> <phrase>The <guilabel>Virtual Hosts</guilabel> Panel</phrase> </textobject> <caption><para>The <guilabel>Virtual Hosts</guilabel> Panel</para></caption> </mediaobject> </screenshot> <para>The following items can be specified for each address:</para> <variablelist> <varlistentry> <term><guilabel>Root directory</guilabel></term> <listitem><para>What the logged-in user sees as the filesystem root (<filename class="directory">/</filename>).</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Banner</guilabel></term> <listitem><para>A file whose contents will be displayed to the user upon connection. The file location is relative to the root set above.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Logfile</guilabel></term> <listitem><para>Transfers will be logged to this file.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Passwd file</guilabel></term> <listitem><para>An alternate password file can be specified. Otherwise the system password file will be used.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Shadow file</guilabel></term> <listitem><para>An alternate shadow password file can be specified. Otherwise the system shadow password file will be used.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Hostname</guilabel></term> <listitem><para>The hostname displayed upon login and inserted as <token>%L</token> in message files.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Administrative email</guilabel></term> <listitem><para>The email address to be inserted as <token>%E</token> in message files.</para></listitem> </varlistentry> </variablelist> <para>Anonymous logins can be allowed or denied.</para> <para>Real users can be allowed or denied access to the virtual server. Specific user can also be allowed or denied access.</para> <para>In the screeenshot, the virtual host <systemitem class="systemname">211.22.55.114</systemitem> has a filsystem rooted at <filename class="directory">/home/ftp/virtual</filename> on the real system. It uses separate password and shadow password files in <filename class="directory">/home/ftp</filename>, displays the hostname <systemitem class="systemname">ganesh</systemitem> and the admin address <quote>root</quote> and allows anonymous logins and logins from all real users.</para> </sect1> </chapter> <chapter id="credits-and-license"> <title>Credits and Licenses</title> <para>&kwuftpd;</para> <para>Application written by Bernhard Rosenkraenzer <email>bero@redhat.com</email>, and is copyright 2000 &RedHat;, Inc.</para> <para>Documentation copyright 2000 by Jonathan Singer <email>jsinger@leeta.net</email>.</para> &underFDL; &underGPL; </chapter> <appendix id="installation"> <title>Installation</title> <para>&kwuftpd; is part of the &kde; 2.0 base packages. It will automatically be installed with your &kde; installation and requires &kde; 2.0 to function.</para> <para>For more information, you should visit the &kde; website at <ulink url="http://www.kde.org/">http://www.kde.org</ulink>.</para> <para>To obtain &kwuftpd; separately, it is part of the kdeadmin package, and should be compiled and installed as indicated in the package's main directory. New versions of kdeadmin can be obtained at <ulink url="ftp://ftp.kde.org/pub/">ftp://ftp.kde.org/pub/</ulink>.</para> <para>To build &kwuftpd;</para> <screen> <prompt>%</prompt> <userinput><command>cd</command> <replaceable>kdeadmin/kwuftpd</replaceable></userinput> <prompt>%</prompt> <userinput><command>./configure</command></userinput> <prompt>%</prompt> <userinput><command>make</command></userinput> Then as root: <prompt>#</prompt> <userinput><command>make</command> <option>install</option></userinput> </screen> <para>You also require an ftpd that can handle the generated ftpaccess files - &kwuftpd; was written for <application>wu-ftpd</application> 2.6.1 (<ulink url="ftp://ftp.wu-ftpd.org/pub/wu-ftpd/">ftp://ftp.wu-ftpd.org/pub/wu-ftpd/</ulink>) You can use the files with <application>wu-ftpd</application> 2.5.0 as well, but don't expect all the features to work.</para> </appendix> </book> <!-- Local Variables: mode: sgml sgml-minimize-attributes: nil sgml-general-insert-case: lower End: -->
