Enter The Freenetrix
The Freenet Help Site
Enter The Freenetrix
Licences used on this wiki
Welcome admin to Freenet WikiServer
Edit Page - Diff - Revisions - Title Search - Preferences - Bottom
Newbie StartGuide for Unix/Linux/OSX/BSD

Note: there are reports of some errors on OSX and BSD when running JVM 1.4.2. If you experience any difficulties, please try/revert to JVM 1.4.1 or 1.5.x and see if that solves the problem.

See also the Top Ten problems & solutions.

[100] Linux/Unix/OSX

Crash Course

The following applies to Unix/Linux/OS X users.


Before running Freenet you must ensure that you have a JVM installed. Currently, Freenet is known to work only with Sun's JVM and the Blackdown JVM.

Java can be installed via your distribution's packaging tool (RPM, apt-get) or manually. If you will be installing Java manually, you can get the installer from http://java.sun.com/j2se/index.jsp. The stable version, currently J2SE 1.5.0, is recommended. More direct link : http://java.sun.com/j2se/1.5.0/download.jsp
Be sure to get the JRE, and not the full JDK, unless you plan to develop Java software. Mac OS X already contains Java on a default installation.

Whenever you think you have Java working run the command 'java -version' and if you get something like this:

  • $ java -version
  • java version "1.4.2_01"
  • Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_01-b06)
  • Java Hot Spot(TM) Client VM (build 1.4.2_01-b06, mixed mode)
You're good to go. If not, check where the Java installer has placed the files. Usually you want your Java installation's bin directory in your $PATH variable so you can run it from anywhere. For example if you installed Sun's 1.5.0_04 JRE to /opt/sun-jre-1.5.0_04/ and the above doesn't work, you would put this in your ~/.profile or equivalent:

Please remember this is an example, find out exactly where your java is installed and what version it is and customise accordingly or it won't work! /opt is quite a common place, look there if you don't know.

Now run 'source ~/.profile' or log in to a new shell for the changes to take effect.

Linux users : if putting the java path in ~/.profile doesn't work it's probably because you're using bash, try putting it in ~/.bash_profile as well.

If you have trouble installing Java, please refer to your distribution's guides on doing so.


Next, get the latest freenet (stable) snapshot from: http://freenetproject.org/snapshots/freenet-latest.tgz
and execute the following commands (or double click on the archive to extract it if that is supported):

  • $ tar -xzvf freenet-latest.tgz
  • $ cd freenet
  • $ chmod u+x *.sh
  • $ ./start-freenet.sh
When you run start-freenet.sh for the first time, there will be some configuration. Most of the values are okay as default, and they all can be changed later by editing "freenet.conf". A few should be looked out for, though. Your listenPort is the port Freenet listens on for incoming connections. The configuration tool will suggest a suitable random one, just accept it unless you know what you're doing.

Your listenPort should if at all possible be available from the outside. If you have a firewall or NAT blocking your connection set up "port forwarding" and poke a hole in the firewall to let it through. See the instructions that came with your router, it's usually done through a nice web browser interface on consumer equipment and is fairly straightforward. This is not *strictly* neccessary now that Freenet has bidirectional connections, but it does significantly help performance.

ipAddress is your IP address as seen by the outside world. If you have a static external IP, lucky you, put it here. Many of us have dynamic IP's however, even on xDSL. If you are one of these people you can make use of a free dynamic DNS service such as that provided by http://www.dyndns.org , and enter your dynDNS hostname here as the address. Make sure you keep it up to date by running an update client whenever your node is online. If your node has an external IP, it should be autodetected by the network and you don't need to enter anything.

Probably the easiest to use dynDNS update client I have seen is DDclient - http://ddclient.sourceforge.net/ . It runs as a daemon itself, so you don't have to mess about with cron, just start it at boot. Its configuration file may look a little complicated at first but you can leave 95% of it commented out, you only need to supply basic things like your username.
Here's an example ddclient.conf with only needed things in it :

 daemon=600                              # check every 600 seconds (10 minutes)
 syslog=yes                              # log update msgs to syslog
 mail=root                               # mail all msgs to root
 mail-failure=root                       # mail failed update msgs to root
 pid=/var/run/ddclient.pid               # record PID in file.
 use=web, web=checkip.dyndns.org/, web-skip='IP Address' # found after IP Address
 login=your_username_here                        # default login
 password=your_password_here                     # default password
 wildcard=no                                     # add wildcard CNAME?
 server=members.dyndns.org,              \
 protocol=dyndns2                        \

Replace your_username_here with your username, your_password_here with your password and your.hostname.here with your dynDNS hostname and you should have a basic working configuration.

Alternatively, a cron program can be used to run an update client periodically for you. I used to use "ipcheck.py" on my dedicated node. I had all the files to do this in / because I don't really know how to use cron and this seemed to work :^) My cronjob looked like :

*/10 * * * * /do_ipcheck.sh

i.e. run "/do_ipcheck.sh" every 10 minutes. do_ipcheck.sh was a simple one line script that ran ipcheck.py with my username/password etc. I made the cronjob just by entering the above text followed by a blank line into a file and doing "crontab filename". You very probably already have a cron program installed.

When you get freenet working remember to update often using update.sh. As a rough guide update stable once a week or so, and update unstable once a day.
NOTE : This isn't accurate right now, updates to 0.5x have slowed to a relative trickle because most work is being done on the 0.7 branch.

You can subscribe to the project mailing lists or just read the archives online (http://www.freenetproject.org/index.php?page=lists) if you want to know exactly when new builds are out, what has changed, etc. Also, the gateway page, seen when you open fproxy, will indicate if a build newer than yours has been seen on the network.

One of the most important configuration settings used to be whether your node was transient (frequently down / changing IP and no dynamic DNS) or not (permenant or mostly so.) What it used to do was ensure any "transient" node never got any requests. However, now that Freenet has bidirectional connections all nodes get requests anyway, and as I understand it this setting does not do anything anymore. Indeed it is no longer even communicated to other nodes. Personally I would set it to "non-transient" and just make an effort to keep your node up as much as you can. If nothing else this will stop the "Frost" client from complaining on startup.

Please, if you have the space, set the data store size to (a lot) more than the default of 256M. If possible it should be at least several GB, as much as you can spare really. The 256MB default was set early on, in days of smaller hard disks, as an adequate size for freesite HTML and graphics but it is much too small for effective sharing of big files, as happens on Freenet today. Big datastores will help both you (content gets cached locally before you even ask for it) and the network. As well as increasing performance for popular files a bigger datastore will help rarely requested, but perhaps important, content "hang on" and not get pushed off the network.

The bandwidth limiting is not perfect. If you have an ISP that only allows some amount of data per month, ideally you should use another tool to control the data flow of freenet, or keep a very open eye on your use. Generally it only overruns a little however so you can most likely get away with just trimming the bandwidthLimit's back a few Kb/s from what you want the real limit to be.

When it finishes building the config, Freenet should start up - a process which can take quite a while - and stay running. You might get some warning messages but that's OK, usually. Do "tail -f freenet.log" if you want to see what's happening, or type "ps ax" after a minute or so and check it's still running. It takes a while (30 seconds minimum) to start up fproxy, so be patient.

Eventually your node should start up. Have patience though! If it crashes, post what happens on http://news.gmane.org/gmane.network.freenet.support and hopefully someone will be able to help you out.

Try visiting http://localhost:8888/ (assuming the node is on your local machine.) You should see the "Web Interface" that is still usually referred to as "fproxy", even though it's really called "mainport" now. This provides a mechanism for monitoring your node and browsing freesites. You are provided with some default "bookmark" links (which you can change) on the front page to start you off. At first the "bookmark" graphics, which are called Active Links, will probably not show up; this is normal, new nodes currently require quite a long time to get integrated.

Make sure your browser is configured to optimise Freenet use as per Speeding Up Freenet tip 2, and the others if you want but that's the important one. Using a Mozilla browser like Firefox is recommended. Mac OS X users: don't use Microsoft IE whatever you do: it's not safe; if you're not a Mac OS X user and do use MS IE, it's not safe for you either so stop it and please let us know how you got it to run on a non-Mac Unix-alike. ;-)

From, go to the Freedom Engine (or one of the other portals) and start surfing. The more you use it, and the longer you leave it running, the better it will get (you'll find more content more reliably and in shorter times). Be prepared for it to really suck at first ;^) As your node integrates into the network it will get better so don't give up early on.

Maybe you want to be able to access the Web Interface from a remote machine or machines. This is especially good if you have a spare PC that can be a dedicated node box, doing nothing but running Freenet, so you can leave it on all the time. It won't need a monitor (nor even graphics card or keyboard) after it's set up, just install ssh on it, set the BIOS to ignore missing keyboard if neccessary then log in remotely to start/stop/update Freenet etcetera.

To allow remote access both to the web interface (mainport) and to FCP clients like Frost / Fuqid / Fuqt / pm4pigs, edit the following entries in freenet.conf like so:


You can add other IPs, comma-separated (no spaces) and/or whole subnets using the usual notation. Make sure you leave (localhost) in there!
After doing this, restart freenet by typing './stop-freenet.sh' and './start-freenet.sh'. Some configuration options can be changed while the node is running but currently this isn't one of them.

-- MB / u

[101] Gentoo

On Gentoo, you simply have to type this as root:
emerge freenet
Before you attempt to configure freenet for the first time, enter the command:
hostname -i
if you get your IP address then you are ready to configure freenet. However, if you get 'hostname: Unknown host' then the configuration will hang before prompting you with the listenPort. If you run the freenet configure through the java debugger you will see that this is due to a Null Pointer Exception. To prevent this you should edit your /etc/hosts file. If you've followed the standard Gentoo install you should be used to using nano to edit files. Edit the hosts file using
nano -w /etc/hosts
If your IP address is and your host name is 'example' and your domain name is 'mydomain' then your file should contain these lines:        localhost  example.mydomain example
Once you've done this, typing hostname -i as above should return your IP address ( in this example). If it doesn't, your configuration might fail.

To configure Freenet, type this as root:
ebuild /usr/portage/net-p2p/freenet/freenet- config
First you will be asked if you want to update your freenet files. You should say yes to this as the jar files in the package are very old. With the current version it is usual to see the following (or similar):
INFO: Native CPUID library 'freenet/support/CPUInformation/libjcpuid-x86-linux.so' loaded from resource
INFO: Optimized native Big Integer library 'net/i2p/util/libjbigi-linux-athlon.so' loaded from resource
These messages are benign and you can ignore them. If you are prompted for a listen port:
listenPort [1234]
You can carry on and configure freenet by accepting the defaults or setting your own values as you see fit. If you don't get this prompt after 30 seconds or so, it is likely due to the hang described above.

Finally type this to start :Freenet

'/etc/init.d/freenet start' and if you want to load Freenet automatically at startup type this 'rc-update add freenet default'.

[102] OSX Note

On Mac OSX, the freenet.conf file will often become corrupted (extra line breaks) if you edit it using vi or pico. Apple Text Edit will work for editing the configuration file.

Also, in the start-freenet.sh there is a java argument:
MaxDirectMemorySize=128m - which doesn't work on the java on the mac osx.

When you comment out (or remove) this line in start-freenet.sh it works fine.

Furthermore, as indicated before, some users of Java version 1.4.2 have had repeated and reproducible kernel panics when they used the newer version/builds of Freenet. Sometimes after a few minutes, sometimes after a few hours. After downgrading the JVM to build 1.4.1_01-99 it seems to work again. Maybe this problem is somehow related with the load a node has. Similar problems have been reported with some BSD variants.

It is recommended for OSX/BSD users, therefore, to use the JVM 1.4.1 version when running Freenet. Alternatively try the current versions (1.5.0.x) which should be faster. If you do, please report on the mailing lists (http://freenetproject.org/?page=lists) whether they work for you or not.

[103] Linux 2.6 / Redhat 9

There is a bug in the Sun JVM (at least the 1.4 versions and possibly 1.5 as well) that causes problems with Linux kernel 2.6 and the kernel that shipped with Red Hat Linux 9. It will cause Freenet to freeze in about an hour (in my machine; the time will vary). To avoid this bug, add the following line into the second line of start-freenet.sh script in the main Freenet directory:

export LD_ASSUME_KERNEL=2.4.1

This will disable the use of pthreads, which will work around the problem but unfortunately causes a hit in performance, since Freenet is pretty heavily threaded.

Newer versions of Sun JVM might fix this problem, so try removing this line and seeing what happens occasionally. Likewise newer versions of Red Hat should hopefully fix the problem, since ultimately the bug is really in the RH9 kernel rather ambitiously using NPTL before it was mature.

[200] (Open) BSD

The Masochistic Way

  • March 2004: I don't do BSD, but as far as i know Kaffe does not run freenet, so regard all the text below as outdated. Use as is/was..
In short, it's a goal (of the v0.7 branch) but isn't here yet.

Here's what I did, or at least what I can remember, for OpenBSD:

Install Kaffe.

 mkdir /usr/local/src 
 cd /usr/local/src 
 cvs -d:pserver:readonly@cvs.kaffe.org:/cvs/kaffe login 
The password is readonly.

 cvs -d:pserver:readonly@cvs.kaffe.org:/cvs/kaffe co kaffe 
 cd kaffe 
 ./configure  --with-includes=/usr/local/include --with-libraries=/usr/local/lib --with-engine=jit3 

 Edit libtool and change need_version=no to need_version=yes 

 gmake install 

Create a Freenet user account.

Choose a partition with lots of space.

 mkdir ~freenet 
 chown freenet ~freenet 

 vi ~freenet/.profile 
Set PATH so that java will be in it.
Set CLASSPATH so that ~freenet/freenet.jar and ~freenet/freenet-ext.jar will be in it.

Everything else is done as the freenet user.

Download the three files you need.
 su - freenet 
 wget http://freenetproject.org/snapshots/freenet-ext.jar 
 wget http://freenetproject.org/snapshots/freenet-latest.jar 
 mv freenet-latest.jar freenet-DATE.jar 
 ln -s freenet-DATE.jar freenet.jar 
I keep multiple versions because sometimes one of them's bad.

 wget http://freenetproject.org/snapshots/seednodes.ref 
Or if you prefer, get someone else's seednodes.ref file.

Configure the node.
 java freenet.node.Main --config 

Optionally, edit freenet.conf by hand to change things you want changed.

Start the node.
 nohup java freenet.node.Main & 

That's just the fundamentals. In actual practice, running Freenet on Open BSD required a bit more tweaking than this. For example, I had to put kern.maxfiles=4096 in /etc/sysctl.conf, and :openfiles-max=512: in the default stanza in /etc/login.conf. And I had to use ksh for freenet's shell, instead of bash. And maybe some other changes, all of which I've forgotten by now.
  • The shell used is probably not an issue anymore, Conrad made the scripts more cross-platform since, try it and see.
Here's what I actually have in ~freenet/.profile:

 ulimit -n 400

 case $SHELL in
  */bash) source ~/.bashrc ;;
  */ksh)  export ENV=$HOME/.kshrc ;;

~freenet/.kshrc just has set -o vi in it. Here's the actual shell script that I run to start freenet
I cleverly named it run

 # Increase number of open files permitted from 64 to 128.
 ulimit -n 400
 # Let process use 256 MB memory (data segment size; this also pull up the
 # virtual memory size, -v, which we can't do directly).
 ulimit -d 262144

 while true; do
    pids=`ps xw 

| grep -v grep 

| grep -q java 

| awk '{print $1}'`

    [ -z "$pids" ] && break
    kill `echo $pids`
    sleep 2

 nohup java -mx 224M freenet.node.Main &

[300] Note: Easy Freenet

Sorry, the instructions for installing an (outdated) version of Freenet with easyfreenet has been discontinued. Current build Freenet nodes will refuse to communicate with outdated versions, leaving you with a node that can't talk to anyone but itself, making it effectively useless.