# A Guide to Freenet Web Site Publishing for the Bold

by giannijohansson@mediaone.net

Here are instructions on how to create and maintain a web site inside Freenet using my PutFiles file insertion tool.

They are targeted at people who are comfortable running command line Java tools. If you are such a person and you can't get these instructions to work, please let me know and I will try to help you out.

-- gj

# Prerequisites

- You need a JVM that supports Freenet.
- You need to have Freenet release 0.3.7 or later. Earlier versions won't work.
- You should be comfortable working at a command prompt.
- You should have a reasonable background in dealing with Java. I don't explain how to install your JVM, or go into deep detail on how to configure CLASSPATH, etc.
- You should be familiar with Freenet. See `(freenet.sourceforge.net)`.

# Other documentation

Before you start, you should read the "Creating websites in Freenet" document on the Freenet web site `(freenet.sourceforge.net/index.php?page=content)`. In particular, you should be sure that you understand how to use SSKs.

While somewhat out of date (as of 3 April 2001), it provides good general background. Ignore the obsolete sections, 1.1, 1.2, and 1.3.

A technical description of MSKs written by the implementor can be found here.

You might also find the manifest tools README interesting.

# Overview

Publishing into Freenet involves three distinct processes: a) inserting the content you want to publish, b) inserting a MapSpace Key (MSK) listing that content, and c) inserting an updated Date Based Redirect (DBR) to the MSK on a regular basis (usually daily).

MSKs are a clever convenience to create human readable namespaces that efficiently map back to CHKs. An MSK is essentially a flat text file that lists a set of human readable file names and the CHK keys that they map to in Freenet. When a Freenet client program (e.g. fproxy) requests a human readable file name through an MSK, it looks up the human readable file name in the mapping and requests the corresponding CHK. The mapping between human readable file name and CHK is arbitrary and can be modified by creating a new MSK.

Freenet doesn't support updating existing keys. This feature may be implemented in future releases, but in the mean time, dynamic updating is supported by Date Based Redirects (DBR).

A DBR is a special control document that can be inserted into Freenet to link to dynamically updated content. When a Freenet client program (e.g. fproxy) retrieves a DBR, it redirects the request to a new URI which is composed of the base URI name defined in the DBR and an update value based on the the current date and time.

This document describes how to create a web site in Freenet by making a DBR that redirects to an MSK listing the files in the site.

The process is as follows. First you manually create the DBR using the freenet_insert command line tool that comes with the Freenet distribution. Each day before midnight GMT you use PutFiles to insert the files into Freenet and to insert an MSK listing them under the next days DBR update.

Note that this last step has changed since the previous version of this HOWTO document. PutFiles now inserts the MSK for you directly under the DBR update, without a redirect. Doing without the redirect increases the realiably of your page, by requiring one less file that can fail.

Here are step by step instructions...

A couple notes before we start

- freenet_insert (*nix) == finsert (Windows)

  If you are using Windows subsititute finsert for references to freenet_insert below.

- Specifying the listening port for the local node

  Unless your local node uses the default port number (19114), you must set `-serverAddress` to use the appropriate port number for your local node on the command line for PutFiles and freenet_insert. e.g.:

  ``

      freenet_insert -htl 45 -serverAddress tcp/127.0.0.1:19117 freenet:CHK@ foobar.txt

  frequest on Windows doesn't require the `-serverAddress` argument, but PutFiles still does.

  The `-serverAddress` argument is ommitted for brevity's sake in the examples below, but you must include it or the examples won't work for you.

- Using the config file mftools.ini to work around line length limits

  Some Window shells have a pitifully short command line length limit. If you find that you can't fit all the arguments to PutFiles that you need on the command line, use the config file instead. See the manifest tools README. for more information on the config file.

# Step 0: Installing Tools

`a) Get Freenet release 0.3.7 or later from:

www.freenetproject.org/index.php?page=release0.3

Or build the latest (non-experimental) snapshot from CVS.

b) Download the jar containing PutFiles from:

freenet:SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/files/0.15c/manifest.jar

This is the compiled jar. If you want to look at the source check out the tools page on my webpage:

freenet:MSK@SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/homepage//manifest_tools.html

c) Add freenet.jar and manifest.jar to your CLASSPATH.

d) Run this command from the command line to check that PutFiles is working.

java relentless.gj.cli.PutFiles

If you don't see a usage message re-check steps a - d.

`

# Step 1: Make A Date Based Redirect

Here's how to use the standard freenet_insert command line tool to create a date based redirect for your site:

`freenet_insert -htl 45 -createUpdate yes freenet:SSK@YOUR_PRIVATE_KEY/SITE_NAME`

You need to have a subspace key to perform this step.

Substitute your SSK keyspace private key for `YOUR_PRIVATE_KEY`, and `SITE_NAME` for the name of your site.

The above command line creates a DBR that's updated once daily at midnight GMT. If you want a different interval or update time, type freenet_insert with no arguments and read the usage information for the required command line arguments.

Note that you only have to insert the DBR once.

Be sure to keep the final public URI that freenet_insert prints out when it finishes. It will be used to form the URI for your site.

e.g. If freenet_insert prints:

`freenet:SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/homepage`

The final URI to access your site would be:

`freenet:MSK@SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/homepage//`

# Step 2: Create The Html Subdirectory

Put all the files for the site that you want to insert in their own subdirectory.

Only relative hyperlinks will work within the MSK namespace.

If you want to link to a Freenet URI outside the MSK namespace use a leading slash but don't include the leading "freenet:".

e.g.

< a href=" /SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/files/0.14/id3-1_4.diffs.txt " > id3-1_4.diffs.txt < /a > < br >

NOT!
< a href=" freenet:SSK@enI8YFo3gj8UVh-Au0HpKMftf6QQAgE/files/0.14/id3-1_4.diffs.txt " > id3-1_4.diffs.txt < /a > < br >

The latter won't work in browsers that don't support the " freenet: " protocol, while the former works in all cases.

Make sure you include a top level index page. You can name it anything you want as long as you change the mskIndex argument to PutFiles. index.html works fine for me.

# Step 3: Run Putfiles

You have to do this step every day before GMT midnight.

The following example assumes you are using this key pair:
Private key : CJupllk3LCd6L-7M4mx5tmyNVPiZP1-4-jihmA
Public key : ~0Wlt3siTTKpmbDO8mKFGnbNgMsQAgE

Obviously, this is only for example, don't use this compromised keypair for anything.

Furthermore it is assumed that you have already inserted a DBR for the site under:

freenet:SSK@~0Wlt3siTTKpmbDO8mKFGnbNgMsQAgE/mysite

Here's a basic command line to make PutFiles insert a directory of files into Freenet and insert an MSK for them under the next days DBR update

    java relentless.gj.cli.PutFiles -simRequests 5 \
                                    -htl 45 \
    				-future 1
                                    -mskURIValue freenet:SSK@CJupllk3LCd6L-7M4mx5tmyNVPiZP1-4-jihmA/mysite
                                    -fromDir directory_name

    -simRequests is the number of conncurrent insert requests to run.
    -htl  is the htl use when inserting files into Freenet.
    -future 1  tells PutFiles to insert the MSK under the next DBR update to
               the URI specified by mskURIValue
    -mskURIValue is the private SSK key to insert the MSK under.
    -fromDir points to the directory to insert.

Note that the relative file names in the MSK contain any subdirectories under directory_name but not directory_name itself.

The full public value for the MSK will be dumped to stdout when PutFiles finishes.

That's it. Once PutFiles finishes you should be able to access the site through the DBR.

NOTES:
Sometimes one or more of the files will fail to insert. You can just rerun the same command line to try again. If you are having persistent problems set the `-retries` option. PutFiles doesn't check for existing CHKs (yet). It just blindly tries to reinsert every file in the directory every time you run it. This isn't normally a problem. It could take a while if you have a very big site (100s of files).

PutFiles supports the standard freenet_insert DBR command line options -- `-update, -increment, -baseline, -future, -past`

# Notes:

# DBR interval

For the sake of simplicity, I assume that the default, daily interval is used when creating the DBR and that the web site maintainer will choose to insert the DBR update for each day on or before Midnight GMT on each day.

This is an oversimplication. It is possible to create DBRs that have other intervals and update times. Run freenet_insert with no arguments to see the command line options for creating DBR's for more info.

Also, it is possible to create the DBR updates before the date that they will be used. e.g. If I am going away for a two week vacation, I can insert the DBR updates for all of the days I will be gone before I leave. Again see the freenet_insert usage message for more information.

# htl value

I've found that if I don't use an htl of about 45 my pages don't propagate reliably.

updated: Tuesday 3 April 2001