<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" 
"dtd/kdex.dtd" [
  <!ENTITY kappname "&kwuftpd;">
  <!ENTITY package "kdeadmin">
  <!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>2002-05-03</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><guisubmenu>More
Applications</guisubmenu><guimenuitem>KWuFTPd</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>File</guimenu>
<guimenuitem>Load /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>File</guimenu>
<guimenuitem>Load Other 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>File</guimenu>
<guimenuitem>Save /etc/ftpaccess</guimenuitem>
</menuchoice></term>
<listitem><para><action>Save changes</action> to
<filename>/etc/ftpaccess</filename>.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Save Other File</guimenuitem>
</menuchoice></term>
<listitem><para><action>Save changes to a file to be
specified.</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Quit</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>

&help.menu.documentation;

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

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;
</chapter>

<appendix id="installation">
<title>Installation</title>

&install.intro.documentation;

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

&install.compile.documentation;

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

