Freenet - how not to Publish a Freesite

Hello! You're probably wondering why I called this document what I called it. The reason is simple: in my experiences with Freenet, I learned a vast deal about what does not work. Many of the actions that seemed simple, straightforward or intuitive to me turned out not to work the way I expected them to. As a result, publishing a relatively simple Freesite took me 5 days.

I hope that I can share my experiences with others who might think like I do. If I can help just one person avoid the frustration that I experienced, then this document is worth the time it took to write.

Of course, a document that contains only DO NOTs isn't very useful -- so in addition to telling you what not to do, this guide also tells you some of the things you should do.

Generating a keypair

• DO NOT generate a keypair by running freenet_insert SVK@ /dev/null. I tried it. It almost works -- a keypair is created, but the resulting private key is much shorter(!) than the private key you get when you run the proper keypair generation command.
• DO generate a keypair with freenet_insert -makeKeypair.
• DO write down both your public and private keys.

Creating your site

• DO NOT use symbolic links! I tried it. It doesn't work.
• DO make full copies of the files in question, instead of using symbolic links. Yes, this means you may have 3 copies of your large data files floating around -- one in the normal place, one in your Freesite directory, and one in your Freenet datastore. I can see no way around this.
• DO use index.html as your index page. This simple fact was not documented anywhere obvious; fortunately, I guessed correctly on this point the first time around. I don't know whether any other filenames may be used as index pages, since I didn't try any others.

Creating your DBR

A DBR is a Date-Based Redirect. The Freenet client programs contain special built-in knowledge of how to handle this -- at 00:00 UTC every day, the client will automatically "roll over" to the next day's keys.

• DO NOT create your DBR in the past. I tried it; I'm not sure whether it works, because the results of this experiment were drowned by all the other errors I encountered. -past 1 looks nice, but I don't believe it can be used to any beneficial effect here.
• DO create your DBR by running freenet_insert -htl 45 -createUpdate yes freenet:SSK@PRIVATE/SITE_NAME where PRIVATE is your private key from above, and SITE_NAME is a string which identifies your Freesite. You can use almost any SITE_NAME you want; I don't know what restrictions there are on the characters used here, but lower-case letters and underscores are definitely allowed, and slashes (/) are almost certainly a bad idea.

Inserting your site

This is the hard part!

• DO use date -u to see what time it really is.
• DO NOT expect to see your Freesite today. You won't be able to see it until 00:00 UTC. If it's currently 22:00 UTC, you'll see it in 2 hours. If it's currently 01:30 UTC, you get to wait 22.5 hours.
• DO NOT insert your site with -future 0 in an attempt to force the insert to happen "today". I tried it. It does not work.
• DO NOT omit the -future 1 parameter altogether in an attempt to force the insert to happen "today". It tried it. It does not work.
• DO get used to the fact that you can't see your site until 00:00 UTC. Really. There's no way to rush it.
• DO NOT insert your site with -fromDir SITE_NAME where SITE_NAME is the subdirectory containing your site. I tried it. If you do this, your site's URI will be freenet:MSK@SSK@PUBLIC/SITE_NAME//SITE_NAME/index.html which is probably not what you want.
• DO change directory into the place where your index.html file lives.
• DO run the command java relentless.gj.cli.PutFiles -simRequests 5 -htl 45 -future 1 -mskURIValue freenet:SSK@PRIVATE/SITE_NAME -fromDir .
  • PRIVATE is your private key from above
  • SITE_NAME is the string identifying your Freesite (it must match what you used when you created your DBR)
  • . (dot) is the current working directory.
• DO NOT use your public key when inserting your site. I didn't try this. I may be a bit slow, but I'm not that dumb. ;-)
• DO wait until 00:00 UTC before you do anything else.

Maintaining your site

• DO know what time zone you're in. I'm in US/Eastern, which is also called EST5EDT. This means I suffer Daylight Savings Time half the year. I do not live in EST. That's Indiana. If you told your Linux system that you live in EST, and you don't live in Indiana, your clock is going to be wrong half the time.
• DO know when 00:00 UTC occurs in your time zone. This requires some arithmetic. For me, 00:00 UTC occurs at either 20:00 EDT or 19:00 EST.
• DO subtract 59 minutes from the set of times you obtained in the previous step; the site update can take several minutes, so we'd like to run it 59 minutes before 00:00 UTC. For me, this special moment occurs at 18:01 or 19:01.
• DO set up a crontab job that runs your site insert at each of the special moments you derived in the previous step. For me, this means I have a crontab entry that looks like this:
  1 18,19 * * * cd $HOME/freenet && ./update
• DO write the shell script update in the appropriate directory. It doesn't matter what directory you put it in, or even what you call it, as long as it matches what the crontab entry says.
• DO put, at the top of your update script, the following command:
  [ `date -u +%H` = 23 ] || exit 0
  This ensures that your script will only run at 23:01 UTC, and not at 22:01 UTC or 00:01 UTC or any other time. This is how we get around the fact that Freenet uses UTC and crontab uses localtime.
• DO make sure that your update script sets PATH and CLASSPATH appropriately. Cron does not read your .bash_profile or /etc/profile.
• DO make sure you change your working directory (with cd) inside the update script before you try to insert your Freesite. We told cron to change to where the update script lives; but this is not necessarily the directory where our Freesite's index.html file resides. In fact, it will definitely be the wrong place if you wish to avoid publishing your update script.
• DO NOT publish your update script if you put your private key in it! If you want to publish your update script, that's fine -- but make sure it reads your private key from some other file outside the Freesite directory.
• DO execute chmod 700 update to make it unreadable by other users on your system -- unless you're reading your private key from some other file. In that case, chmod 600 the-file-that-has-my-private-key.

Viewing your site

• DO wait until 00:00 UTC before you try to view your site.
• DO use the URI freenet:MSK@SSK@PUBLIC/SITE_NAME// where PUBLIC is your public key and SITE_NAME is the string you used to identify your Freesite when you created your DBR.

Links

If you got this far without understanding any of what I just said, then start with The Freenet Project.

If you know what Freenet is, but not an SSK, then read the Old Freenet Publishing docs. But ignore everything that talks about Javascript.

If you know Freenet pretty well, but have no idea what PutFiles is, then read GJ's Guide to Freenet publishing. This is the most important document for you to read, since it's by the author of PutFiles, which is what's doing all the grunt work here. GJ's guide is only on Freenet, so you'll have to set up your web browser to handle the freenet: URI prefix, or paste to your Freenet file retrieval utility.