You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdenetwork/doc/kpf/index.docbook

411 lines
13 KiB

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
<!ENTITY kappname "&kpf;">
<!ENTITY package "tdenetwork">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>
<book lang="&language;">
<bookinfo>
<title>The &kpf; Handbook</title>
<authorgroup>
<author>
<firstname>Rik</firstname>
<surname>Hemsley</surname>
<affiliation>
<address>&Rik.Hemsley.mail;</address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
<copyright>
<year>2002</year>
<holder>&Rik.Hemsley;</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>
<date>2003-09-30</date>
<releaseinfo>1.0.1</releaseinfo>
<abstract>
<para>
&kpf; allows you to share files over a network.
</para>
</abstract>
<keywordset>
<keyword>KDE</keyword>
<keyword>public</keyword>
<keyword>fileserver</keyword>
<keyword>HTTP</keyword>
</keywordset>
</bookinfo>
<chapter id="introduction">
<title>Introduction</title>
<para>
&kpf; provides simple file sharing using &HTTP; (the Hyper Text
Transfer Protocol,) which is the same protocol used by web sites to
provide data to your web browser. &kpf; is strictly a public
fileserver, which means that there are no access restrictions to shared
files. Whatever you select for sharing is available to anyone.
</para>
<para>
&kpf; is designed to be used for sharing files with friends, not to
act like a fully-fledged web server such as
<application>Apache</application>. &kpf; was primarily conceived
as an easy way to share files with others while chatting on
<acronym>IRC</acronym> (Internet Relay Chat, or <quote>chat
rooms</quote>.)
</para>
<para>
Typical usage: &kpf; is set up to serve files from the <filename
class="directory">public_html</filename> folder in your home
folder. You wish to make a file available to some people with
whom you are chatting online. Rather than send them each an
email with the file attached (some may not even be interested,)
you copy the file into your <filename
class="directory">public_html</filename> folder and announce
to those listening that your file is available at
http://www.mymachine.net:8001/thefile
</para>
</chapter>
<chapter id="using-kpf">
<title>Using &kpf;</title>
<sect1 id="kpf-basics">
<title>&kpf; basics</title>
<para>
&kpf; runs as an applet inside &kicker;. This means that it
takes up little space on your screen and its status is always
visible. To start the &kpf; applet,
<mousebutton>right</mousebutton> click on &kicker; and choose
<guimenu>Add Applet to Panel...</guimenu> to open the <guilabel>Add
Applet</guilabel> dialog. Select <guilabel>Public File Server</guilabel> and
click the <guibutton>Add to Panel</guibutton> button.
</para>
<para>
&kpf; employs the concept of shared folders. You may choose
one or more folders to make public, and all files in that folder
(and any subfolders) will be shared.
</para>
<para>
Please be extremely careful about which folders you
share. Remember that all files in the folder and its
subfolders, including <quote>hidden</quote> files
(<quote>dotfiles</quote> to the techies) will be made
available to the world, so be careful not to share sensitive
information, such as passwords, cryptographic keys, your
addressbook, documents private to your organization, &etc;.
</para>
<para>
Once &kpf; is running, you will see a square applet with a
thin sunken bevel and an icon depicting an <guiicon>hot air
balloon</guiicon>. The balloon is visible when no folders are being
shared.
</para>
<para>
To share a folder, <mousebutton>right</mousebutton> click
on the balloon icon and a popup menu will appear, containing
only one item, <guimenuitem>New
Server...</guimenuitem>. Selecting this entry will cause a
<quote>wizard</quote> to appear, which will ask you a few
simple questions. Completing the questions will set up a
folder for sharing.
</para>
<para>
There is an alternative to using the applet directly when you
want to share a folder. &kpf; is integrated with &konqueror;.
</para>
<para>
With &konqueror; open and displaying a folder,
<mousebutton>right</mousebutton> click on the background and
bring up the <quote>Properties</quote> dialog. On install,
&kpf; added a <guilabel>Sharing</guilabel> tab to this
dialog. You will be offered the option of starting &kpf; if it
is not running. Choosing <guibutton>Ok</guibutton> will send a
signal to the &kpf; applet, asking it to add a new share.
</para>
</sect1>
</chapter>
<chapter id="share-config">
<title>Share configuration</title>
<sect1 id="listen-port">
<title>Listen port</title>
<para>
For each folder that is shared by &kpf;, a new network
<quote>port</quote> is opened. A <quote>port</quote> is simply a number used to uniquely identify a
network service. When someone uses a program (&eg; a web browser)
to connect to a machine, it is directed to the service by specifying
the address of the machine and the <quote>port</quote> on which the service is
running.
</para>
<para>
The <quote>port</quote> concept allows one machine to run more
than one network service. Services you might use every day
include &HTTP; (the web,) usually connected to by port 80,
&SMTP; (mail sending,) usually on port 25,
and POP3 (mail receiving,) usually on port 110.
</para>
<para>
Usually, when you connect to a network service, you do not need
to specify which <quote>port</quote> you want to connect
to. This is because the ports are standardized, so anyone
connecting to port 80 on a network machine expects to find an
&HTTP; (web) server.
</para>
<para>
&kpf; is not a <quote>standard</quote> service, so 8001 was
chosen for the default port.
</para>
<para>
The second folder you share will offer to listen on port 8002,
with the number being incremented each time you start a new share.
</para>
<para>
Within certain boundaries, you are free to choose whichever port
number you wish, for a share.
</para>
<para>
It is usual for port numbers below 1000 to be reserved for
<quote>system</quote> services, &ie; those under the control
of the machine's administrator, therefore you may find that
attempting to use anything below 1000 will simply not work.
</para>
<para>
&kpf; tries to warn you when it cannot <quote>listen</quote>
on a port. It does this by displaying a <guiicon>broken
connection</guiicon> icon over the top-left corner of the
graph. &kpf; attempts to stop you assigning more than one
share to the same port, but it will not attempt to stop you
setting a share to listen on a port which is already occupied
by another service, for example your <quote>real</quote> web
server.
</para>
<para>
If you see the <guiicon>broken connection</guiicon> icon,
<mousebutton>right</mousebutton> click on the bandwidth graph
and choose <guimenuitem>Configure...</guimenuitem> Now try
changing the listen port and pressing
<guibutton>Ok</guibutton>. Assuming that this time you picked
a free port, you should see that the <guiicon>broken
connection</guiicon> icon disappears, and you should now be
able to connect to the share.
</para>
</sect1>
<sect1 id="bandwidth-limit">
<title>Bandwidth limit</title>
<para>
The term <quote>bandwidth</quote> refers to the amount of data
that may be transmitted over a connection during a period of
time. Techies may be overheard referring to how
<quote>fat</quote> their <quote>pipe</quote> is. The analogy
is apt.
</para>
<para>
&kpf; allows you to set a limit on how much bandwidth will be
used by a particular share. This is useful when you want to
avoid your network connection being saturated by people
downloading from your shares. If you are on a modem, for
example, you only have a few kilobytes per second to
yourself. Limiting the bandwidth used by your &kpf; shares
will allow you to keep a portion of the bandwidth for your own
use.
</para>
<para>
As just mentioned, &kpf; measures bandwidth in kilobytes per
second, or kB/s for short. A typical modem transfers about 5kB/s on
average, so limiting the total use of all &kpf; shares to a value
less than this may be wise, depending on how you are using &kpf;.
</para>
</sect1>
<sect1 id="follow-symlinks">
<title>Follow symbolic links</title>
<para>
A symbolic link is a special file which is a reference to another
file (or folder) in your filesystem. By following the link,
you reach the file or folder referred to - the link is generally
transparent.
</para>
<para>
By default, a &kpf; share does not allow the following of
symbolic links. This means that, for example, if you have a
share pointing to <filename
class="directory">/your/home/folder/public_html</filename>
and you create a link inside <filename
class="directory">public_html</filename>, pointing to
<filename class="directory">/tmp</filename>, then anyone
requesting <filename class="directory">/tmp</filename> will
see the contents of your <filename>/tmp</filename> folder.
</para>
<para>
In general, it's a bad idea to allow the following of symbolic
links in this way. The main reason this is allowed is so that
you may have symbolic links inside the shared folder, which
point to another place inside the shared folder. This can
be useful if you're serving up an entire
<quote>website</quote> - which as mentioned previously, is not
the intended use of &kpf;.
</para>
<para>
Just be careful not to link to anywhere on your file system that
might hold sensitive information (or have a symbolic link in it
somewhere that points to sensitive information!)
</para>
</sect1>
</chapter>
<chapter id="faq">
<title>Questions and Answers</title>
<qandaset id="faq-questions">
<qandaentry>
<question>
<para>Why does &kpf; not include any security mechanisms?</para>
</question>
<answer>
<para>
In truth, &kpf; does include various measures designed to help
prevent the user accidentally providing access to sensitive
information. There is no password protection and no encryption.
This is by design, as will be explained.
</para>
<para>
The more security measures that are added to a service, the
safer people feel when using it. Sadly, to ensure real security,
the user needs to have a good understanding of the issues involved.
For example, providing password protection is no use if the user
does not know how to pick a good password. Therefore the decision
was made to provide zero security, in the hope that the user will
find it easier to understand what this means than to spend months
or years learning about the complexities of network security.
</para>
<para>
The concept is simple. If you specify that a folder is
shared, it's shared to the world. If you don't want to make
it available to the world, don't share it.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>
<chapter id="credits">
<title>Credits and License</title>
<para>
&kpf;
</para>
<para>
Program copyright 2002 &Rik.Hemsley; &Rik.Hemsley.mail;
</para>
<para>
Documentation copyright 2002 by &Rik.Hemsley; &Rik.Hemsley.mail;
</para>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;
<para>
&kpf; is released under the MIT license.
</para>
</chapter>
<appendix id="installation">
<title>Installation</title>
<sect1 id="getting-kpf">
<title>How to obtain &kpf;</title>
&install.intro.documentation;
</sect1>
</appendix>
&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
End:
-->
<!-- vim:tabstop=2:shiftwidth=2:expandtab -->