diff options
Diffstat (limited to 'doc/kpf/index.docbook')
| -rw-r--r-- | doc/kpf/index.docbook | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/doc/kpf/index.docbook b/doc/kpf/index.docbook new file mode 100644 index 00000000..5dff1c74 --- /dev/null +++ b/doc/kpf/index.docbook @@ -0,0 +1,410 @@ +<?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 "kdenetwork"> + <!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 (⪚ 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 --> |