This document pertains to the 0.2 release of Freenet.

Contents

• 1. Package
• 2. Requirements
  • 2.1. Software Requirements
  • 2.2. Requirements for Operating a Freenet Server
  • 2.3. Requirements for Operating a Freenet Client
• 3. Installation
  • 3.1. Installation on a Unix/Linux Platform
  • 3.2. Installation on a Windows Platform
• 4. Freenet Components
  • 4.1. The Freenet Server
  • 4.2. The Java Client
  • 4.3. The GUI Client
  • 4.4. The Liberator
  • 4.5. FCRC
  • 4.6. fproxy
• 5. Using Freenet
  • 5.1. Local Setup
  • 5.2. Internet Setup
• 6. Troubleshooting
• 6.1. Notes on using Freenet with Kaffe

1. Package

Since Freenet is currently in pre-beta stage, there is no formal distribution. You can download the current CVS snapshot which contains all Freenet components available up to now. The package is a single zipped tar archive. If you are on a Windows environment you'll probably need a tool like WinZip to extract the files.

2. Requirements

2.1. Software Requirements

Depending on which component you plan to use, you will need one ore more of the following programs installed and configured on your system:

• Java Development Kit 1.1 or later, or a compatible implementaion (available at http://java.sun.com/) if you want to run the server, Java command-line clients, or fproxy.
• Swing Components (included with JDK 1.2 and later) if you want to run the GUI client
• Perl Version 5.001 or later (available at http://www.cpan.org) if you want to run the Liberator client or FCRC

2.2. Requirements for Operating a Freenet Server

The following requirements are applicable only if you want to run a productive Freenet server. None of them is needed to use one of the clients or to test/develop with local dummy servers (see section 5.1)

• A permanent Internet connection
• A static IP address
• No Firewall or Proxy between your machine and the Internet

A note on fixed IPs and permanent connections: You can operate a useful node even if you do not have a permanent connection and/or a static IP. But please keep in mind that a node which is not reachable most of the time is useless for Freenet as a whole, so you should operate a node only if you are connected most of the day and if your IP address does not change too often (most cable modem setups meet these criteria, for example). Nodes are actually storing information, and the information stored in your node is not available if you are not connected.

2.3. Requirements for Operating a Freenet Client

Although Freenet is just in the development stage at the moment, and there is not much content available up to now, you might be interested in simply running a client against the existing nodes in the Internet Doing so is possible without a permanent connection or static IP, but being behind a firewall could pose a problem since you must be able to accept inbound and outbound connections on at least two ports.

3. Installation

First, you should extract the CVS snapshot into a temporary/working directory. Take care that the directory structure and filenames are preserved. In the following, I will assume you have extracted the archive to /tmp/Freenet or c:\temp\Freenet, respectively.

Second, the server and Java clients have to be built. There are scripts for both Unix/Linux and Windows environments, which invoke the javac compiler.

In the third step, the .class files have to be installed in their final location.

Finally, you may have to change the .freenetrc file to make adjustments (see section 4.1 )

3.1. Installation on a Unix/Linux Platform

Extract the archive to a temporary directory:

cd /tmp
tar xvzf Freenet-2000xxxx.tgz

Build server and Java console client (path to javac must be set correctly):

cd /tmp/Freenet/scripts
./build.sh

If you are using kaffe, you should use this script instead:

./kbuild.sh

Also see: 6.1. Notes on using Freenet with Kaffe

If you want the GUI client, you'll have to build it separately:

cd ..
export CLASSPATH=/tmp
make GUI

Now you start the installation script, which moves the .class files to the target location (e.g. /usr/local/; if you are not root, you may have to chose another directory) and creates the little scripts and symbolic links freenet_server and freenet_client.

cd scripts
./install.sh

Since the GUI client installation is not done by install.sh, you have to copy the .class files separately.

cd ../client
cp *.class /usr/local/freenet/Freenet/client/

3.2. Installation on a Windows Platform

Extract the archive to a temporary directory, e.g. with WinZip, then build the .class files:

cd c:\temp\freenet\scripts
build.bat

Build the GUI client separately, if you want to:

cd c:\Temp\Freenet\client
set CLASSPATH=C:\temp
javac GUI

Install the .class files:

cd c:\Temp\Freenet\scripts
install.bat

Again, the GUI client has to be installed separately:

cd c:\Temp\Freenet\client
copy *.class c:\freenet\client

4. Freenet Components

4.1. The Freenet Server

The servers, also called nodes, are the main part of Freenet. Freenet can only exist if there are enough people who are running servers, so we really want to encourage you to run a server if you can. The server takes its configuration out of the .freenetrc resource file, which has several parameters to set. These settings are described in the .freenetrc file. Additionally, you can override the parameters in the .freenetrc by specifying them at startup (e.g. freenet_server -listenPort 12345)

You can start the server with freenet_server (or fserve.bat if you are on Windows). Under Unix/Linux you have to kill the server manually if you want to stop it. If it is the only java process you are running, you can use killall java; otherwise you will have to look up the process ID using ps.

4.2. The Java Client

The java client is a simple client written for debugging purposes. To insert data, you must specify the key to store it under and the filename containing the data (or the length of the data if reading from stdin). To request data, you must specify the key to request and (optionally) a filename to put the retrieved data in (otherwise stdout).

There is another optional parameter which is the hops-to-live. This is basically the number of nodes which your operation will traverse -- for requests, the number of nodes to look for your data on; for inserts, the number of nodes to store your data on. It defaults to 5, but the appropriate value depends on your patience and the size of the network. http://freenet.sourceforge.net/inform.php will give you an idea of the current size of the network. Because of Freenet's adaptive routing, you will typically only need an HTL which is a small fraction of the total number of nodes.

On Unix/Linux platforms, you can start the client with freenet_insert or freenet_request, respectively. These commands are finsert and frequest for Windows users. Type the commands with no arguments to get usage information.

4.3. The GUI Client

The GUI client is not finished, but you can have a preview now. Unix/Linux users start it with:

java Freenet.client.GUI (from the /usr/local/freenet directory.)

Windows users type java -classpath c:\temp\freenet Freenet.client.GUI

4.4. The Liberator

Liberator is a Freenet client written in Perl. In the distribution, you can find it in the directory contrib/Liberator. Its parameters are more or less the same as the Java client.
You can start Liberator by typing perl liberator.pl in the Liberator directory.

4.5. FCRC

FCRC is a Freenet->HTTP gateway. It can be found in the distribution in contrib/FCRC. Just drop fcrc.pl in your cgi-bin directory and you have your gateway ready. You might have to make some adjustments in the fcrc.pl program to account for the way your web server is set up.

4.5. fproxy

fproxy is another Freenet->HTTP gateway which uses a proxy server instead of CGI -- useful if you are not running a webserver or do not have cgi-bin access. It can be found in the distribution in contrib/fproxy. See the README for instructions.

5. Using Freenet

Now that installation is done, you are ready to enter the Internet of the 21st century! In the following section, I will give you examples which show you how you can actually participate. If something does not work, check the troubleshooting section.

5.1. Local Setup

The local setup is intended for all the people who are not enjoying the advantages of a permanent connection to the Internet, or at least a flatrate, but are interested in testing/developing Freenet anyway. There is a script test5.sh contained in the distribution which will start 5 servers on the local machine. Note that in test5.sh, the Freenet servers are invoked with the parameters informRead no -informWrite no. These parameters tell the Freenet servers not to report their existence to http://freenet.sourceforge.net/inform.php, the place where many permanent servers are listed during this testing phase of Freenet. To make sure your local Freenet servers know each other, you should copy the nodes.config file to your working directory before starting the servers.

When the local servers are running, you can check if everything is working. Create a file test.txt in your working directory. We will now insert that file into Node #1:

freenet_insert -serverAddress tcp/localhost:10001 -htl 3 my_test_key test.txt

If everything worked fine, you should see an output like Data insert -> tcp/127.0.0.1:10001. Now we are testing whether we can get the data back from our Freenet node #3:

freenet_request -serverAddress tcp/localhost:10003 -htl 3 my_test_key result.txt

Look at your working directory: You should now have a file called result.txt which contains the requested data.

Something did not work? Check out the troubleshooting section.

5.2. Internet Setup

You can, of course, use Freenet when you have connection to the Internet (in fact, that is what Freenet has been designed for :-)) In this section, I am assuming you have set up a a node locally on port 19114 and registered it (-informURL http://freenet.sourceforge.net/inform.php -informWrite yes -informRead yes).

We will now insert data into your local Freenet node. Create a file test.txt in your local directory. Now we can insert that file:

freenet_insert my_test_key test.txt

If you got an output like DataInsert -> tcp/127.0.0.1:10001, then everything is fine. Though, chances are good your output reads more like Key collision, insert again under different key. Quite obviously, you have tried to insert a key which already exists in Freenet. If that happens, you should use another key, maybe something like Freenet/{your name goes here}/test_key_1.)

If you did succeed in inserting your data, we will now test whether it can be obtained from other nodes. First we must determine the address of an existing Freenet server. There are two possible ways to do that. First, you could check the output of your local node and maybe you will see there the addresses of the nodes your node has been talking to. The other possibility is to look at the inform.php page with a web browser.

Let's assume now you have found out the address and port of another Freenet server:

freenet_request -serverAddress tcp/{remote_node_address}:{remote_node_port} my_test_key

If everything is ok, you should get an output just like DataReply <- tcp/127.0.0.1:10001. Then the received data will either be displayed on your screen or saved in the file you specified on the command line. If you cannot reach the remote node, you should select another node (the information in inform.php is not always up to date). If you get an output like The key you requested could not be found within HTL hops, you should increase the hops-to-live. Maybe it is also a good idea to check your input for typos. If all that does not solve the problem, you should read the troubleshooting section.

6. Troubleshooting

Trying desperately, but Freenet is not willing to work? Running into an error without having the slightest idea why? Don't worry, this is not unusual when evaluating a project in pre-alpha state. But chances are very good that your problem has been solved before. In this section, I will give you some hints on how to retrieve a solution for your problem.

First, READ THE FAQ!. There are some common problems already covered in it. If that does not help, you should have a look at the freenet-chat and freenet-dev mailing list archives. For your convenience, I have webzipped the archives at http://www.i-drive.com/evilchris. I am sure that most of the possible problems have already been discussed in these lists. If you have read all the mailing list, and you are still clueless, you can also post your question to freenet-chat. But please keep in mind that many people on the list are spending much time in the development of Freenet, and there are few resources to operate the mailing list in a hotline-style fashion. So please only ask if everything else fails.

6.1. Notes on using Freenet with Kaffe

The current alpha releases of Freenet will run with Kaffe, an excellent Free implementation of a Java virtual machine and class libraries. There are however a few issues that we hope to have resolved as soon as possible:

• Kaffe currently has trouble reading and writing node addresses to the web page used to initialize a nodes knowledge of other nodes on the network. This fucntion is just a temporary method meant as a simple bootstrap or IV while the network is still small, and as such is optional. You can disable it by setting informRead=no and informWrite=no in .freenetrc file or at the command line.

  Since it cannot read any node addresses off the web, you need to manually initialize your node with at least one other node's address. To do so, either get an address from somebody you know who already runs a node, or copy the addresses currently on this page, and put them in a file called nodes.config in your node's working directory.

• Kaffe also has trouble reading the stored cache on the disk when it is restarted. This means you will have to reinitialize the node by the above procedure every time you start it. (Note also that Kaffe will crash if it tries to read a cache saved by another java VM, so if you are changing from java to Kaffe, clear your .freenet/ subdirectory.)