Origami README

Copyright (C) 2007-2010 Christer Edwards <christer.edwards@ubuntu.com>

Please send questions, suggestions and bug reports to:
https://launchpad.net/origami/

Origami is licensed under the GPL v2.

-----

DESCRIPTION :
#############

Origami is a tool for managing Linux based Folding @ Home distributed
computing clients.  Origami allows you to install, archive, restore and update
user information via a simple command-line interface.

Origami can also manage multiple Folding @ Home distributed computing clients
via ssh access including installation (mass network deployment), network
archiving, network restoration, updating user information and more.

If you're not familiar with Stanford's Folding @ Home distributed computing
client you can find more information at http://folding.stanford.edu.

In a nutshell, you can donate unused cpu cycles to medical research
regarding Alzheimer's, Huntington's Disease (HD), Cystic Fibrosis, Cancer and
P53, Osteogensis imperfecta, Parkinson's Disease (PD), and Antibiotics.

LOCAL INSTALLATION :
####################

Origami allows for local Folding @ Home installations very
easily.  To install to your local machine see the below examples:

origami install
-- install to the local machine using the default 'Anonymous' user and '0' team.
This will default to i386 architecture.

origami install -u FOLDINGUSER -t TEAMNUMBER
-- install to the local machine using a custom FOLDINGUSER and TEAMNUMBER.
This will default to i386 architecture.

origami install -p smp|amd64 -u FOLDINGUSER -t TEAMNUMBER
-- install to the local machine with 64bit support using custom FOLDINGUSER
and TEAMNUMBER.

REMOTE INSTALLATION :
#####################

Origami allows for remote Folding @ Home installations very easily.  To
install to a list of network locations you will need two prerequisites:

1)  Generate a list of machines you want to install within a ~/.origamirc.
    This list can use resolvable hostnames or IP addresses, one per line
2)  You will need ssh access as the root user in order to use any of the
    network functionality.

NOTE:   if you are using Ubuntu you will need to set a root user password.  This
        can be done using the command 'sudo passwd root'.

TIP:    You may also want to setup ssh key-authentication for passwordless
        access to these machines.  To do this do the following:

        On a central machine run: ssh-keygen -t dsa
        Select the default location (ENTER)
        You may also want to leave the password field blank (ENTER)
        
        When the key has been generated, copy the public key to each remote
        machine using: ssh-copy-id -i ~/.ssh/id_dsa.pub $remote-machine

        This process should allow you to access the remote machines without
        the need of a passphrase.  This can help automate remote
        installations, archiving and monitoring.

origami deploy
-- install to any machine listed in the ~/.origami file.  This will use the
default 'Anonymous' user and '0' team.  This also defaults to i386
architecture.

origami deploy -u FOLDINGUSER -t TEAMNUMBER
--install to any machine listed in the ~/.origamirc using a custom FOLDINGUSER
and TEAMNUMBER.  This also defaults to i386 architecture.

origami deploy -p smp|amd64 -u FOLDINGUSER -t TEAMNUMBER
--install to any machine listed in the ~/.origami with 64bit support using a
custom FOLDINGUSER and TEAMNUMBER.

ADDITIONAL LOCAL OPTIONS:
#########################

Origami allows for local archiving, monitoring, removal or renaming of the 
Folding @ Home client information.  To archive (backup) your Origami data, 
monitor your progress, completely remove Folding @ Home from your machine, or
simply update FOLDINGUSER and TEAMNUMBER information see the following examples:

origami archive
--archive all data in the /var/lib/Origami/ directory and store in ~/.Origami/

origami monitor|status|stats
--display the current status of Folding @ Home as well as current progress

origami erase
--completely remove Folding @ Home data from the machine. USE WITH CAUTION!

origami name -u FOLDINGUSER -t TEAMNUMBER
--update the client.cfg file used by Folding @ Home to report work unit
data.  Any future reports will use the new information, previous results
remain reported as previous FOLDINGUSER and TEAMNUMBER.

origami start
--start the local client

origami stop
--stop the local client

origami migrate
--migrate a folding.sh installation to an origami installation

ADDITIONAL REMOTE OPTIONS:
##########################

Origami allows for remote archiving, monitoring, removal or renaming of 
the Folding @ Home client.  To archive (backup) your Origami data from 
multiple machines, monitor the progress on each client, erase all data from 
each machine see or update the FOLDINGUSER and TEAMNUMBER see the following 
examples:

origami network-archive
--archives all data in the /var/lib/Origami directory on any machine listed in
the ~/.Origami file.  Data is stored by hostname-date.tar.bz2 in the
~/.Origami directory locally.

origami network-monitor
--display the current status of Folding @ Home as well as current progress on
any machine listed in ~/.Origami

origami armageddon
--completely remove Folding @ Home data from any machine listed in
~/.Origamirc.  USE WITH CAUTION!

origami network-name
--update the client.cfg file used by Folding @ Home to report work unit data
on any machine listed in ~/.origamirc.  Any future reports will use the new
information, previous results remain reported as previous FOLDINGUSER and
TEAMNUMBER.

origami network-start
--start all accessible clients listed in ~/.origamirc

origami network-stop
--stop all accessible clients listed in ~/.origamirc

CUSTOM CONFIGURATION:
#####################

Origami generates a cron job for the dedicated Origami user.  By default
this cron job is commented out (inactive).  If you would like this cron job to
be active by default use the -c|--cron 1 option at installation.

origami install -c 1

If you would like to customize daily start and stop times for the Folding @ Home 
client customize this cron job via the following:

crontab -u origami -e

This should edit the cron table for the Origami user, and you should see a few
lines similar to:

#0 8  * * * /etc/init.d/origami stop >/dev/null
#0 17 * * * /etc/init.d/origami restart >/dev/null

To activate this stop-at-8:00am and start-at-5:00pm schedule for Folding @
Home simply uncomment the two lines.  If you would like to alter the start and
stop times simply update the two values using a 24H clock syntax.

This feature was added to Origami in the 0.5.2 release.

Origami 0.6.9 introduced the bigpackets and passkey options (new with FAH 6.x).

origami install -k PASSKEY | --key PASSKEY

Using a passkey will certify that your results are only your results.  Its like
putting a password on your submissions.

If you have a more or less powerful machine you might want to use different sized
work units.  Options are 'small', 'normal' or 'big'.  The default is 'normal'

origami install -b big | --big big

----------

Origami can also be automagically installed via a kickstart file, commonly
used in Redhat, Fedora and similar distributions.  If you would like to
automate the setup of Folding @ Home at the time of machine installation
simply add the following lines to the %post section of your kickstart file:

## Origami addition to kickstart begin
%post --nochroot
cd /mnt/sysimage/tmp
wget -c http://zelut.org/projects/origami/origami-0.7.3.tar.gz
tar -xf origami-0.7.3.tar.gz
echo "/tmp/origami-0.7.3/origami install &> /tmp/origami.log" >> /mnt/sysimage/etc/rc.local
## Origami addition to kickstart end

Be sure to update the "Origami install" line with any custom FOLDINGUSER,
TEAMNUMBER, 64bit support or cron support as needed.  See local installation options above.

This feature was added to Origami in the 0.4 release.
----------

TESTING:
########

Currently, as of version 0.7.3, Origami has been tested on:
Ubuntu 9.04
Ubuntu 8.10
Ubuntu 8.04
Ubuntu 7.10
Ubuntu 7.04
Ubuntu 6.06.1
RedHat Enterprise Linux 5
Oracle Enterprise Linux 4
SuSE Linux Enterprise Server 10
SuSE Linux 10.1
centOS 5
Fedora Core 6
Fedora 7
Fedora 8
Fedora 9
Foresight Linux 1.4.1
Arch Linux
Gentoo
-----

INCLUDES :
##########

This archive should also be accompanied with the following files:
origami
README
copyright
changelog
