
This is part of the Objectify project documentation.
Copyright (C) 2005, 2006, 2007, 2008, 2009   J. Scott Edwards
See the file README for copying conditions.


PLEASE NOTE: This software is Alpha software, meaning it is not finished and
it most likely contains bugs.  Use it at your own risk.  It is free software:
you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3
of the License, or (at your option) any later version.  If you did not
receive the license you can write to:

      Free Software Foundation, Inc.
      59 Temple Place - Suite 330
      Boston, MA 02111-1307, USA.

Or view online at: http://www.gnu.org/copyleft/gpl.html

                              *******************
                              *  PLEASE READ!!! *
  *****************************                 ******************************
  *                                                                          *
  * I recommend using the file-import --recursive (-r) option with caution   *
  * if you have have backup (.dif) files enabled.  In this version it only   *
  * creates one backup (.dif) file per session, so even if you are only      *
  * importing small files, they all go into one .dif file and they add up.   *
  * The larger the .dif file the longer it takes to sort.  I recommend that  *
  * if you are going to be importing a large amount of files, to do a backup *
  * of the whole archive (with compress_archive), disable backup, import the *
  * files, do another backup, and then re-enable the backups.                *
  *                                                                          *
  ****************************************************************************


****************
  Installation
****************

There is no installation at this point in the project.  Although it now uses
GNU autoconf to configure some parameters, some things must still be configured
by hand, by editing the /etc/objectify.conf file.

There really are only three functions that are working in this version
(Alpha_30):

The first function is simply storing information about a person, first 
name, middle name, last name, date of birth, and mobile phone number.

The second function is storage of regular computer files.  They can be
imported, listed, verified and exported.

The third function is disc logging.  It can record the MD5 and SHA1
checksums of the files on a disc and log copies of that disc.
NOTE: it can only deal with files in the root directory of a disc and
CANNOT handle sub-directories at this time.

In this version the person information is not linked to the files in
any way.  Although the plan is to connect them up, they are completely 
separate in this version.


**************************************
 Step 1: Download the public objects
**************************************

The first thing that you must do is download the latest Public Objects.
The code cannot be compiled or installed without the public objects file.
It can be downloaded from the sourceforge.net/projects/nwos web page, under
the "Public Objects" package.  You should just get the latest one.

After you have done that, you need to unzip it:

	gunzip public-090522-0030.gz


*****************************
 Step 2: Build the programs
*****************************

Note: on some systems you will need to make sure that the header files and
libraries for openssl are installed.  For example on Ubuntu/Kubuntu Linux
you need to install the libssl-dev package before building:

  sudo apt-get install libssl-dev

First you need to point to the public objects downloaded in Step 1:

  export OBJECTIFY_PUBLIC_PATH=/whatever/public-090522-0030

or

  setenv OBJECTIFY_PUBLIC_PATH /whatever/public-090522-0030

Then you should be able to just do the usual configure and make:

  ./configure
  make

If you want a debug version you can do the make as follows:

  make type=DEBUG

NOTE: now that ./configure is used the big endian thing should happen
automatically.


***********************************************
 Step 3: Install in /usr/local/bin (OPTIONAL)
***********************************************

You can install the programs in the /usr/local/bin directory with the following
command:

  sudo make install

The following steps assume you have done so.  If you don't install them in
/usr/local/bin you will need to prefix the commands with an absolute path
for example: /usr/src/objectify-XXX/prep_disk.


***************************************
 Step 4: Configure the storage medium
***************************************

If you don't want to create a configuration you can just set the environment
variables and use Objectify without a configuration file.  For example, to use
Objectify with the default ~/.objectify/private.obj file for storage, you just
need to tell it where the public objects file is:

  export OBJECTIFY_PUBLIC_PATH=/whatever/public-090522-0030

or

  setenv OBJECTIFY_PUBLIC_PATH /whatever/public-090522-0030

And skip the remainder of this section.

Note: you can also set environment variables for the private object storage,
where the log files, and the backup (.dif) files are written.  See the
objectify.conf file for more information.

There are two possible ways to store the data for this system.  The first is
to allocate an entire disk or disk partition for storage.  The second is to
allocate a normal file for storage.

As of version 26.6 the default path for the private.obj is:

  ~/.objectify/private.obj

This is the safest thing so that each user has her or his own storage and
there is no risk of two users accessing the storage at the same time.  If
you want to use a different file for storage see the instructions below.

As of version 26.4 the disk and file paths can be configured using the file
/etc/objectify.conf.  There is no need to edit the config.h.in file any more.
Copy the objectify.conf file to /etc:

  sudo cp -pi objectify.conf /etc

To use an entire hard drive you can edit the /etc/objectify.conf file and set
the private variable, for example, as follows:

  private /dev/sdb

To use a disk partition for storage you can edit the /etc/objectify.conf file
and set the variable, for example, as follows:

  private /dev/sda8

To use a file you can edit the /etc/objectify file and set the values, for
example, as follows:

  /var/lib/objectify/private.obj

Note: although it says "Sparse_File" it is actually just a regular file.  I
found out that using a sparse file for this was extremely inefficient.  To
store 100 megabytes in a sparse file used gigabytes of disk space.  The
system now does not work with a "sparse" file.

NOTE: I have tested this system on OpenBSD and found that it will *NOT* work
correctly using a partition or an entire disk.  So on OpenBSD the only option 
is to use a file at the present time.  I have successfully used a file on
FreeBSD systems, I have not tried using a disk partition for storage.  And I
have not tried NetBSD or any other system yet.  I suspect most other systems
will not allow a disk drive or a disk partition to be used for storage.
To date the only systems I have successfully used the partition and entire
disk options on, are the various GNU/Linux distributions.

As of version Alpha_22 (0022) the public objects are not stored in the same
storage as the private objects.  Instead the public object file is just
read directly.  So you also need to point to the public objects file in the
/etc/objectify.conf file as well (the following is the default):

  public /usr/local/share/objectify/public.obj

You can also use a symbolic link (or just put the public objects file in the 
/etc/objectify.conf file above).  To create a symbolic link to the public 
objects file downloaded in step 1:

  sudo ln -s /wherever/public-080315-0027 /usr/share/objectify/public.obj

Or you could just point directly to the file in the objectify.conf file:

  public /wherever/public-080315-0027

If you don't want to edit the /etc/objectify.conf file, I have set the
config.h.in to "~/.objectify/private.obj".

In version Alpha_26.2 I added a new feature which creates a backup (.dif) file
each time additions are made to the system.  To activate this feature you have
to edit the /etc/objectify.conf file and define the "backup" variable to the
directory where you want the backup files written.  For example, one possible
way to use it is to have it write the backup files to a USB stick.  Another way
would be to just have it write the backup files to local directory and then
each time you are finished using the system copy the files to a remote machine.

To store the files on a USB stick change the "backup" variable in
/etc/objectify.conf to:

  backup /media/usbdrive/

Please note that if you do this, the USB stick will need to be in place before
inputting any information to the system.

Also note that when using backup files it creates a new separate backup file 
each time the system is started.  The system has to sort the blocks stored in
the backup file into order and so I don't recommend importing many large sized
files at the same time.  I recommend keeping the size of imports to less than
maybe 20 megabytes per import.  When I have imported groups of files larger
than that is sometimes takes several minutes to do the sort.



************************************************************************
 Step 5: Prepare the storage
************************************************************************

To prepare the disk, disk partition, or file for storage, run the following
command:

  prep_disk

When it has formatted the storage it will ask for a pass phrase.  As of the
Alpha_29.4 release an asterisk is printed for each character typed in the pass
phrase.  If you are in a private location, you can enter 'show' at the pass
phrase prompt, it will go back to the way it was in prior versions and print
each character typed.  If you enter 'last' it will display the last character
typed, but all of the previous characters will be hidden with an asterisk.

Type 'help' at the pass phrase prompt for more information and commands.

On the topic of pass phrases.  I believe a longer one (34 characters or more) 
may be slightly more secure than a shorter one (minimum is 10 characters),
although I cannot say for sure.  In general the longer the pass phrase the
better, I.E. a sixteen character pass phrase is better than a ten character
pass phrase.

And you should always follow good password practices.  Using 'abcdefghij'
or '1234567890' is a really bad idea.  You could use a lyric from an (obscure)
song and change it around a bit.  For example, instead of "She spat her thrash
metal lyrics right into my mind" you could do: "[she spat her thrash metal
lyrics right into my mind!".  (From the song "Backlash Love Affair" by Richard
Thompson: http://www.richardthompson-music.com/song_o_matic.asp?id=179)

I should remind you that I cannot guarantee your data is absolutely secure in
this system.  It is encrypted and scrambled so to the best of my knowledge it
is secure, but again, use this software at your own risk.


************
 Upgrading 
************

Upgrade 0021 to 0022:

	compress_archive compressed-070610-0021

	-- Upgrade to version 22

	restore_archive compressed-070610-0022

Upgrade 0022 to 0023:

	compress_archive compressed-070620-0022

	-- Upgrade to version 23

	convert_0022_compressed_to_0023 compressed-070620-0022 compressed-070620-0023
	restore_archive compressed-070620-0023

Upgrade 0023, 0024, 0025, 0026 or 0027 to 0028:

	compress_archive compressed-080604-0027

	-- Upgrade software to version 28

        prep_disk --no-private
	restore_archive compressed-080604-0027
        update_files_0028      <-- If you have multiple pass phrases
                                    this must be run for each one.

    NOTE: there is no difference in the headers or disk layout  between 
    0024 and 0025, the version was changed to insure that the public 
    objects and the code matched up correctly.  In fact the compressed
    versions of 0023, 0024, 0025, 0026, 0027 and 0028 are all compatible.

Upgrade 0028 to 0029:

	compress_archive compressed-080611-0028

	-- Upgrade software and public objects to version 29

        prep_disk --no-private
	restore_archive compressed-080611-0028

Upgrade 0029 to 0030:

	compress_archive compressed-090711-0029

	-- Upgrade software and public objects to version 30

        prep_disk --no-private
	restore_archive compressed-090711-0029

   or

        -- Get a second medium for storage, such as an external USB drive.

        **** WARNING - WARNING - WARNING - WARNING - WARNING - WARNING  **** 
        ****                                                            ****
        **** This will destroy ALL contents on the external USB drive!! ****
        ****                                                            ****

        -- For this example assume that the normal storage is in
        -- ~/.objecitfy/private.obj

	export OBJECTIFY_PRIVATE_PATH=/dev/sdg
        prep_disk --no-private
        copy_0029_to_0030 ~/.objectify/private.obj /dev/sdg

        -- Verify that copy was successful, for example by running the
        -- 'file-check' program.  Then you can copy the new archive back
        -- to the original storage location:

        unset OBJECTIFY_PRIVATE_PATH
        sync_archive /dev/sdg ~/.objectify/private.obj



*****************************
 Thanks for trying it out!!
*****************************

I have added a couple of documents on how I use the system in the "docs"
directory.

Please send me your suggestions, comments, etc. at j.scott.edwards.nwos@gmail.com

