
PLEASE NOTE: This software is really just a prototype.  Use it at your
own risk.  It is licenced free under the GPL, see the file LICENSE.
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


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

There is no installation at this point in the project.  You will have to
configure it by hand, by editing the config.h file.

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

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-070411-0021.gz


***************************************
 Step 2: Configure the storage medium
***************************************

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.

To use an entire disk partition you can edit the config.h file and set the
values, for example, as follows:

  #define DEFAULT_TYPE_RO Drive_Or_Partition_RO
  #define DEFAULT_TYPE_RW (DEFAULT_TYPE_RO + 1)
  #define DEFAULT_FILE "/dev/hdb"

To use an entire disk partition you can edit the config.h file and set the
values, for example, as follows:

  #define DEFAULT_TYPE_RO Drive_Or_Partition_RO
  #define DEFAULT_TYPE_RW (DEFAULT_TYPE_RO + 1)
  #define DEFAULT_FILE "/dev/hda8"

To use a file you can edit the config.h file and set the values, for example,
as follows:

  #define DEFAULT_TYPE_RO Sparse_File_RO
  #define DEFAULT_TYPE_RW (DEFAULT_TYPE_RO + 1)
  #define DEFAULT_FILE "/home/username/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 not tried the other BSD's yet,
but I suspect they will have the same limitation.  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
config.h file as well (the following is the default):

  #define DEFAULT_PUBLIC_PATH "/usr/share/objectify/public.obj"

You will need a symbolic link (or just put the public objects file in the 
config.h file above).  To create a symbolic link to the public objects file 
downloaded in step 1:

  ln -s /wherever/public-070609-0022 /usr/share/objectify/public.obj

Or you could just point it directly to the file:

  #define DEFAULT_PUBLIC_PATH "/wherever/public-070609-0022"


*****************************
 Step 4: Build the programs
*****************************

Then you should be able to just do a make:

  make

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

  make type=DEBUG

NOTE: on big endian machines (like PowerPC) the SHA1 functions need extra
attention.  Right now you must compile sha1.c by hand with the extra define:

  -DWORD_BIGENDIAN


***********************************************
 Step 5: 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 6: Prepare the storage 
******************************

If you have selected (in Step 2) to use a disk partition or an entire disk for 
storage you can prepare the disk as follows:

  prep_disk

The 32M is the amount of disk space (32 megabytes) it reserves for storing the 
public objects.  The remainder of the partition or disk will be used for
private objects.  The public space *MUST* be a multiple of 16 megabytes (one 
chunk).  At this time the public objects really only use a bit over 4 megabytes, 
but the size may increase dramatically, so I usually allocate some extra space.
If you are only playing with this you can set the public space to 16M (which is
the minimum).

If you selected a file as the storage you will need to specify the amount of
space to reserve for private objects as well:

  prep_disk 2G

This will create a file of 2080 megabytes for storage.

When it has formatted the storage it will ask for a pass phrase.  I currently
don't try to hide the pass phrase, so it will print out to the screen.  This
is because I was initially using only very long pass phrases that proved to
be difficult to enter in reliably when you couldn't see what you were typing.

Since then I have modified it so you can use shorter pass phrases, but I have
not changed the program to mask them yet.

On the topic of pass phrases.  I believe a longer one (34 characters or more) 
will be slightly more secure than a shorter one (minimum is 10 characters).
Although I cannot say for sure.  I should also mention here that I cannot
guarantee that your data is stored secure.  It is encrypted so I believe that
it is, but again, use this software at your own risk.

NOTE: if your storage is large it can take a significant amount of time to
prepare it.  For example, a 200 gigabyte drive can take almost 2 hours to
complete.


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

I should have done a better job of keeping this section up to date.  These
are the last few that I can remember.  If you have an archive older than
these, please e-mail me at j.scott.edwards.nwos@gmail.com and I will try
to help you upgrade.

Upgrade 0021 to 0022:

	compress_sparse compressed-070610-0021
	upgrade to version 22
	expand_sparse compressed-070610-0022

Upgrade 0022 to 0023:

	compress_sparse compressed-070620-0022
	upgrade to version 23
	convert_0022_compressed_to_0023 compressed-070620-0022 compressed-070620-0023
	expand_sparse compressed-070620-0023

Upgrade 0023 to 0024:

	compress_sparse compressed-070630-0023
	upgrade to version 24
	expand_sparse compressed-070630-0023



***********************************************************
 Using the "computer" program to store person information 
***********************************************************

After installation you can run the "computer" program to create a person 
and add a mobile phone for a person.  It can also describe a person or state 
or return a person's phone number.  

The "computer" command can be run in two ways.  It can execute one command
from the command line as follows:

    > computer what is george\'s phone number

Note: it has to have a back slash before the apostrophe or the shell will
want a matching closing quote.

Alternatively, "computer" can be run interactively by just typing:

    > computer

It will then prompt you for commands.  The commands "computer" accepts in 
this version are:

   "add person" - adds a new person to the database.

   "add city" - adds a new city to the database 
                (not of much use in this version).

   "describe <name>" - describes any person(s) with the name <name> in 
                       the database.

   "list cities in <state>" - lists the cities in the database for state 
                              <state>.

   "<name>'s mobile phone is <number>" - adds the phone number <number> 
                                         to the person <name>.

   "what is <name>'s number" - prints out the phone number for the person 
                               <name>.


***************************************
 Storing computer files in the system
***************************************

You can store files encrypted in the system as follows:

  import_file *.jpg

This will store all of the jpg files in the current directory to the system.
The current version CANNOT deal with subdirectories correctly!  Do not use
absolute or relative paths, just a file name in the current directory.

You can adjust the security vs. speed using the following options:

    --minimal-security

         This will give maximum speed for storing and reading the file,
         but because it is stored in almost sequential blocks on the
         disk it may be easier for a cracker to decode.

    --very-low-security

         This will give slightly reduced speed, but spread the file out
         further on the disk to make it a little harder to find the
         pieces.

    --low-security (default)

         This spreads the file out even more on the disk, but is a somewhat
         slower.

    --medium-security

         Spreads the file out even more in storage, quite a bit slower.

    --extreme-security

         Stores each block of the file in random places in storage.  This
         provides the most difficutly in finding the pieces of the file,
         but is extremely slow.  I would not recommend using this for large
         files, it could take hours to read it from the disk. 

To retrieve the files from the system you can use the following command:

   export_file <file names>

You can export all the file stored as follows:

   export_file "*"   

You can verify files using the following command:

   verify_file <file names>

You can verify and then delete the files with the remove option:

   verify_file --remove <file names>

NOTE: file globbing doesn't work correctly in most of these programs yet.

Globbing should work in the list_files program:

   list_files "*.jpg"

You can also get list_files to print the MD5 or SHA1 sums (but not at
the same time):

   list_files --md5 my_file.txt



***********************************
 Keeping a record of backup disks
***********************************

There are some extra programs to log discs burned.  This version cannot deal
with subdirectories and will likely crash and burn in some horrible way.

The way I use this feature is as follows:

  I make a back CD or DVD in the normal way, with all of the tarballs for
  example in the directory /tmp/backup.  I first create a disc list in the
  system as follows:

     cd /tmp/backup
     disc_list *

  At this point it will ask for a label, which must be 12 characters.  I use
  the date and three digits sequential number for the label such as:

     20070413-001

  It will then record the file name, file size, and MD5 and SHA1 sums of all 
  the files.  My logic is that even if say MD5 and SHA1 are compromised in the 
  future having both type of checksums is still pretty safe because I can't
  imagine that it would be possible for one cracked file to still match both
  of them at the same time.

  Then after I burn a disk I mount it and do the following:

     cd /mount/cdrom0
     log_disc *

  It will read all the files from the disc and if it matches the disc list
  created above, it will ask which copy of the disk it is, and then where
  it is stored.

  You can see what discs you have stored with the following command:

     list_discs

  And if you want to see what files are on the discs:

     list_discs --contents


*********************
 Backup and Restore
*********************

There are a couple of programs to allow an Objectify archive to be compressed
and later restored.

To save the data use the following:

   compress_sparse <compressed file name>

NOTE: 'sparse' is a holdover from when I was using sparse files for storage.  The
compress_sparse program is used to save the objects stored on any of the types
of storage.

To restore storage from a compressed file, use the following commands for a
partition or entire disk:

   prep_disk --no-private
   expand_sparse <compressed file name>

Or for a file: 

   prep_disk --no-private 2G
   expand_sparse <compressed file name>

NOTE: the size of partition or file MUST match the size of the file or disk
partition that the compressed file was created from.  It CANNOT restore into
a different size in this version.

Also note that restoring the file with 'expand_sparse' is very slow to a large
disc drive (can take hours).

Finally, there is a program 'diff_compressed' that compares two compressed files
(the first file must be an older version of the second file):

   diff_compressed compressed-070401 compressed-070408

This will output to stdout all of the blocks that changed or were added.  It
cannot handle deleted blocks!

This command will output all of the changed and added blocks to a file:

   diff_compressed compressed-070401 compressed-070408 diff-070401-070408

And then you can use that diff file to "patch" a copy of the earlier file to
create the newer file as follows:

   patch_compressed compressed-070401 diff-070401-070408 compressed-070408


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

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

