
    L i b e r ( a t o r )   F r e e s i t e   I n s e r t i o n
                              H O W T O

by Travis Bemann <tabemann@wisc.edu>

Easy freesite insertion with Liber(ator) utilizes a range of features
of Liber which include personal subspaces, date based redirect
insertion, multiple file insertion, metadata generation, and mapfile
insertion.  Note that there is a variety of methods of multiple
insertion combined with mapfile generation and insertion, but only one
will be shown here, which will allow simple insertion of directories
into Freenet combined with date based redirects

One's files for a freesite should all be organized in a single root
directory, which will make freesite management and insertion
significantly easy.  It allows insertion of the entire freesite in a
single step, without having to enter a list of different files and
directories to insert (for one can simply set the working directory to
the root directory of the freesite and use a single all-inclusive
wildcard to insert the entire contents of that directory and all
subdirectories).  It also aids in keeping track of what is actually on
a freesite, for after a freesite update has been inserted the contents
of that directory are identical to the contents of the freesite.

The easiest and most general method of freesite insertion is to use
the insert files/directories as CHKs and map the path names relative
to the working directory to names within a mapfile that is inserted
under a specified name under one's configured personal subspace.  To
be used practically for a freesite, this must be combined with date
based redirect item/target insertion, which in this case will only
effect the inserted mapfile.  Furthermore, this should be combined
with MIME type metadata generation and modification date metadata
generation, which will be useful to clients accessing one's freesite.
The standard command format for this if one were using daily updates,
one were updating a freesite for tomorrow, one would have the
default mapfile item name be index.html, and one wants to insert all
the files and directories in the working directory would be

liber -s -m -d 1 -D index.html --insert-map-ssk-chks <mapfile name> *

OR

liber --with-suffix-mime-type --with-modify-date --date-redirect-item=1
--map-default=index.html --insert-map-ssk-chks <mapfile name> *

The -d (--date-redirect-item) [present offset] [interval] [offset]
option specifies the actual nature of the date based redirect being
used as well as the offset from the present in number of intervals for
which insertion is occurring.  By default the "present offset" in
intervals is 1. Interval and offset are both in seconds, and specify
the time interval between date based redirect items and the offset
between what is regarded as time zero for the date based redirect and
time zero for the "epoch" (1 January 1970), respectively.

The -s (--with-suffix-mime-type) specifies that file suffixes be
converted into MIME type metadata entries whenever possible.  It uses
the mappings specified in the configured suffix to MIME type mapping
file, if one is specified, and otherwise the ones compiled directly
into Liber from the suffix to MIME type mapping file provided with
Liber.

The -D (--map-default) [name] specifies the name within the multipart
map that will be used as a default name if no name is specified in a
map-based URI.  If this is omitted, then no name will be assumed as a
default name for a map-based URI.

-i (--with-insert-date) cannot be used, for unlike -m
(--with-modify-date) it will generate different metadata for each time
files are inserted as CHKs, and therefore new CHKs will be created
every time a freesite is inserted, rather than just when files are
created or modified.  This would defeat the reinforcing of files
within Freenet through their requesting and mirroring for files would
be effectively replaced for each interval at which a freesite is
inserted.

One note is that splitfiles will be generated as needed, which is by
default if the files in question are equal to or over 256K in size.
Note that this threshold can be changed by using the -S
(--splitfile-block-size) size option, which specified both splitfile
part size and the threshold minimum splitfile size in bytes.  While
one can try to prevent splitfile creation by setting this threshold to
a ridiculously large value, splitfile creation actually helps often
because smaller splitfile parts are individually less likely to be
dropped out of datastores than single large files due to datastore
item deletion being more likely to remove large files than smaller
files.

To actually insert a date based redirect into one's personal subspace,
one uses the command

liber --insert-date-redirect-ssk <name> [interval [offset [target]]]

where <name> is the name within the subspace where the date based
redirect is to be inserted.  Interval refers to the interval (in
seconds) between date based redirect updates, and by default is 86400
seconds (1 day).  Offset refers to the offset of the zero time for the
date based redirect from the zero time of the "epoch" (1 January 1970)
in seconds, and by default is zero.  Target refers to the URI (without
the date based redirect time affix) targeted by the date based
redirect; note that it is by default the *same* as the subspace URI
that the date based redirect is located.  Note that it is easiest and
generally best to have the mapfile referred to by the date based
redirect at the same URI as the date based redirect; therefore, it is
in this case completely unnecessary to specify a date based redirect
target.