FreePastry NAT/Firewall Configuration

This page is designed to help you configure FreePastry for your particular NAT/firewall setup. It covers FreePastry 2.0.

If FreePastry detects an invalid configuration, it will prompt the user for how to proceed. However if you are a developer, you should read over this document to understand how FreePastry will behave in various scenarios so you can pre-configure FreePastry to do the appropriate behaviour for your application.

The document has 3 sections. The first shows you how to configure FreePastry's parameters. The second section consists of quick links to help you configure FreePastry based on your particular setup. Some require you to run with additional libraries in your classpath, some require to adjust your parameters. The third is a detailed explanation of how FreePastry's firewall configuration works.


Definitions:


How to adjust FreePastry's parameters.

Quick links for your particular setup.

Detailed information.


Adjusting FreePastry's parameters

About FreePastry's Parameters

Because FreePastry is a research project used for a variety of purposes, there are a lot of "knobs" that can be adjusted. We have attempted to tune these knobs for the most common configurations, but over the years we have had requests to adjust various aspects of FreePastry for the developer/researcher's unique purposes. Thus we decided it would be useful to have a central place for all of these kinds of configurations rather than adjusting constants in the code. To make this as useful as possible, FreePastry's paramter system has the following capabilities:

How FreePastry "reads" the parameters.

Every PastryNode has access to the Environment. To read a parameter, FreePastry calls environment.getParameters().getXXX("parameter_name"). A parameter can be of various types including ints, strings, and InetAddresses. See the JavaDoc for Parameters for more information.

How FreePastry initializes the parameters.

Most applications use the default constructor for the Environment. This will load a "default" parameter file from the jar called freepastry.params. If java can find a file in the working directory called "user.params" it will load this as the mutable parameter store. Any values in this file will overwrite the default configurations stored in the jar.

Note:If you want to use a different mutable parameters filename than "user.params", you can use the single argument constructor of Environment. If you wish to have additional defaults in your application, you can call the 2 argument constructor of the Environment.

Format of the config file.

Internally, FreePastry's Parameters system uses java's java.util.Properties class. Thus the format is defined here. There are 3 ways to adjust FreePastry's parameters:

Adding a config file.

If your application uses the default Environment constructor, it will search for a user.params file in the working directory. If it finds one, it will use it.

Thus if you want to add/modify the parameter "external_address" and set it to "123.45.67.89:1234" do the following.

1) Create a text file named user.params in your working directory.

2) Add the following line to freepastry.params

external_address = 123.45.67.89:1234

Changing the default freepastry.params file included in the Jar.

Before building (with ant), edit the file located in the source distribution in jars/freepastry.params. The documentation for the parameters is in the file.

Changing the params programatically.

Right after you create the Environment, call getParameters().setXXX("param_name");

Thus if you want to add/modify the parameter "external_address" and set it to "123.45.67.89:1234" do the following.

    Environment env = new Environment();
    env.getParameters().setInetSocketAddress("external_address",new InetSocketAddress(InetAddress.getByName("123.45.67.89"),1234));

Specific configurations.

I'm not firewalled.

FreePastry should work fine for you by default. Sometimes it may fail the firewall test which verifies bidirectional connectivity to the bootstrap. If this happens, it means that your connectivity to the Bootstrap node is too poor for FreePastry to get any communication through, and thus freepastry incorrectly assumes you are firewalled. If you want to disable this test set:

firewall_test_policy = never

It is also possible that while you do have an internet routable address, there is still a firewall blocking one or more of your ports. Verify that you don't have blocked ports.

I'm running the entrie network on my LAN (or a single computer), which happens to be behind a NAT.

Disable UPnP altogether by setting this:

nat_search_policy = never

Note that you need to re-enable this if you wish to join/create a network that goes over the internet.

UPnP: Let FreePastry configure my NAT for me.

Many firewalls can configure port forwarding programatically. See
UPnP Internet Gateway Device for more information. FreePastry uses SBBI's UPnPLib to configure the NAT.

Enable UPnP on your router if you haven't already done so. If you have trouble with this check your router's documentation online at your manufacturer's site.

Include these libraries in your classpath when you run the FreePastry based application. They can be found in the source distribution.

commons-jxpath-1.1.jar:commons-logging.jar:sbbi-upnplib-xxx.jar
So, to run the lesson3 tutorial:
java -cp .:FreePastry-2.0b2.jar:commons-jxpath-1.1.jar:commons-logging.jar:sbbi-upnplib-1.0.3.jar rice.tutorial.lesson3.DistTutorial 9001 10.9.8.7 9001

I want to manually configure my port forwarding settings in my NAT.

Configure forwarding of both UDP and TCP on the same port that you are using. Check out
www.portforward.com for help.

If you have a dynamic address (your ISP may re-assign your IP address):

probe_for_external_address = true

Note:The external port and local port must be the same for this to work. In other words you can't forward port 9300 -> 9001, you must use the same port.

If you have a static address (your ISP doesn't change your IP address everytime you reboot your router):

Set this parameter to the address you set up forwarding. Note that it is ok to have different external port from local port.
external_address = 123.45.67.89:1234

STUNT: Use NAT hole punching.

We're investigating using
STUNT to do NAT hole punching. However we are still in the investigation phase of this project.

Detailed explanation of FreePastry NAT settings.

Hairpinning