# The &kpf; Handbook

## Introduction

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

&kpf; is designed to be used for sharing files with friends, not to act like a fully-fledged web server such as Apache. &kpf; was primarily conceived as an easy way to share files with others while chatting on IRC (Internet Relay Chat, or chat rooms.)

Typical usage: &kpf; is set up to serve files from the `public_html` 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 `public_html` folder and announce to those listening that your file is available at http://www.mymachine.net:8001/thefile

## Using &kpf;

### &kpf; basics

&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, right click on &kicker; and choose Add Applet to Panel... to open the Add Applet dialog. Select Public File Server and click the Add to Panel button.

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

Please be extremely careful about which folders you share. Remember that all files in the folder and its subfolders, including hidden files (dotfiles 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;.

Once &kpf; is running, you will see a square applet with a thin sunken bevel and an icon depicting an hot air balloon. The balloon is visible when no folders are being shared.

To share a folder, right click on the balloon icon and a popup menu will appear, containing only one item, New Server.... Selecting this entry will cause a wizard to appear, which will ask you a few simple questions. Completing the questions will set up a folder for sharing.

There is an alternative to using the applet directly when you want to share a folder. &kpf; is integrated with &konqueror;.

With &konqueror; open and displaying a folder, right click on the background and bring up the Properties dialog. On install, &kpf; added a Sharing tab to this dialog. You will be offered the option of starting &kpf; if it is not running. Choosing Ok will send a signal to the &kpf; applet, asking it to add a new share.

## Share configuration

### Listen port

For each folder that is shared by &kpf;, a new network port is opened. A port 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 port on which the service is running.

The port 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.

Usually, when you connect to a network service, you do not need to specify which port 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.

&kpf; is not a standard service, so 8001 was chosen for the default port.

The second folder you share will offer to listen on port 8002, with the number being incremented each time you start a new share.

Within certain boundaries, you are free to choose whichever port number you wish, for a share.

It is usual for port numbers below 1000 to be reserved for system 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.

&kpf; tries to warn you when it cannot listen on a port. It does this by displaying a broken connection 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 real web server.

If you see the broken connection icon, right click on the bandwidth graph and choose Configure... Now try changing the listen port and pressing Ok. Assuming that this time you picked a free port, you should see that the broken connection icon disappears, and you should now be able to connect to the share.

### Bandwidth limit

The term bandwidth 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 fat their pipe is. The analogy is apt.

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

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

### Follow symbolic links

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.

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 `/your/home/folder/public_html` and you create a link inside `public_html`, pointing to `/tmp`, then anyone requesting `/tmp` will see the contents of your `/tmp` folder.

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 website - which as mentioned previously, is not the intended use of &kpf;.

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

## Questions and Answers

Why does &kpf; not include any security mechanisms?

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.

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.

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.

## Credits and License

&kpf;

Program copyright 2002 &Rik.Hemsley; &Rik.Hemsley.mail;

Documentation copyright 2002 by &Rik.Hemsley; &Rik.Hemsley.mail;

&underFDL;

&kpf; is released under the MIT license.

## Installation

### How to obtain &kpf;

&install.intro.documentation;
&documentation.index;