Origami Documentation
Description
Origami allows you to install, monitor, archive and restore Folding@Home data on your local machine. It supports install-time configuration of username, team, work-unit size, architecture (32bit or 64bit), scheduling, passkey and requesting specific work-unit types (-advmethods, -bigadv, etc).
Origami also supports centralized (client/server) management of multiple installations. From a central location (ie; server1) you can deploy Origami to any number of ssh-accessible clients. Afterwards, the central server can start, stop and monitor each of the clients individually or collectively.
Note: Remote management beyond status reporting requires Administrator (root / sudo) privileges on the remote machines.
For those that are not able to dedicate their machines 24x7, Origami supports cron-based scheduling. This can be used to start and stop the Folding@Home client at pre-determined times. See the CRON section below for details.
QUICK START
If you'd like to dive right in using the default configuration, simply run:
sudo origami install
Installation - Local Client Configuration
There are a number of configuration options that can be set for a Folding@Home client. This page will outline those configuration options, how to use them, and how to manually change them should the need arise.
USERNAME
The first, and generally one of the most important, options is the username definition. Folding@Home allows each client to track its progress by a unique username. You can verify that your preferred name is not already in use here.
You may choose any name you like, as long as it contains only letters or numbers (to insert a space, you may use the underscore "_" character). If you choose your email address as your username, we will use the full email address but NOT print the full email address. Instead, just the part before the @ sign will be used in any stats listing, etc. User names are also case sensitive.
To configure a username at installation, simply run:
sudo origami install -u USERNAME
If no username is defined, the default user 'anonymous' will be used.
TEAM NUMBER
The second common configuration option is the team number definition. Folding@Home allows each user to contribute as part of a team. There are thousands of teams, contributing their work as a competitive group. Teams are often made up of special interest groups, Linux distributions, universities, or a number of other possibilities.
If you'd like to create your own group, you can generate a team here.
To configure a team number at installation, simply run:
sudo origami install -t TEAMNUMBER
If no team number is defined, the default team number '0' will be used.
ARCHITECTURE
Folding@Home offers different binaries depending on the system architecture and installation. To define the architecture, and download the
appropriate client, simply run:
sudo origami install -p amd64
If no architecture is defined, the default architecture 'i386' will be used.
SCHEDULING
Origami allows simple configuration of cron-based scheduling. This allows you to only run the Folding@Home client during pre-defined hours of the day. It is common for some users to only run the client overnight, or to disable it during general business hours. The default schedule, when activated, is to disable the Folding@Home client during the hours of 8:00am and 5:00pm.
To activate the default cron-based schedule, simply run:
sudo origami install -c 1
To edit the schedule to better fit your needs, you'll need to manually edit the cron job. To do this, simply run:
sudo crontab -u origami -e
WORK UNITS
The Folding@Home servers can assign work-units of different sizes. The sizes, measured 'small, normal, and big' are meant to facilitate contributors in two ways. First, different work-unit sizes may be more appropriate for different processor speed. Second, each size work-unit is a different size download. A 'big' work unit is a larger download than a 'small' work unit.
To configure a preferred work-unit size, simply run:
sudo origami install -b SIZE [small|normal|big]
If no size is defined, the default size of 'normal' will be used.
PROXY SETTINGS
If your network requires a proxy for outbound connections, you'll need to configure this in order to accept and return work-units to the Folding@Home servers. The current allowed settings are 'port' and 'host'.
To configure proxy information for your network, simply use:
sudo origami install -P PORT -H HOST
If no proxy settings are defined, the default configuration of no proxy requirements are set.
Note: Both 'port' and 'host' are required when configuring proxy settings.
PASSKEY
The Folding@Home servers allow you to bind a secret 'passkey' to your username to ensure that you get proper credit for your work. Because, technically, anyone can fold under any name, a passkey is a way to further secure your username as your own. You can generate a passkey for your account here. For more information about the passkey system, see the Passkey FAQ.
To configure your assigned passkey, simply run:
sudo origami install -u USERNAME -k PASSKEY
If no passkey is defined, none will be used. Defining a username in combination with a passkey is required. Passkey definition is required for all network deployments.
COMBINING OPTIONS
It is possible to combine a number of Origami configuration options at once. As an example, to configure both username and team, simply run:
sudo origami install -u USERNAME -t TEAMNUMBER
To configure any number of the above options (in no particular order):
sudo origami install -u USERNAME -t TEAMNUMBER -c 1 -p amd64 -b big -k PASSKEY -P port -H host
Installation - Network Client Configuration
Origami supports installation of multiple clients at once, done over a secure SSH connection. There is no limit to the number of clients you install using this feature, the only requirements are:
- Direct SSH access to the host
- Administrative privileges on the host (root / sudo)
To manage network deployments you'll need to generate a list of hosts in a configuration file. The default configuration file is: ~/.origamirc. Hosts can be defined by fqdn, hostname or IP, or a combination. The only requirement is that it is directly accessible from the "master". An example configuration file for network deployment would be:
# ~/.origamirc
192.168.0.5
charlie
hostname.domain.tld
192.168.0.8
Network Deployment
Network-deployed installation is similar to local installation in that it uses and offers the same options. In the case of a network deployment however the username (-u USERNAME) and passkey (-k PASSKEY) are both required.
To deploy Origami to a list of networked hosts and apply custom configuration, simply run:
sudo origami deploy -u USERNAME -k PASSKEY
Any or all of the options outlined in the Local Installation section are also applicable to network deployments.
Client Management
ARCHIVE
Origami facilitates in backing up your work progress. This can be useful if you need to reinstall your machine or migrate to a new machine. I designed this functionality when I was an Instructor and would need to rebuild my classrooms weekly. At the end of the week I would archive the current progress and then restore it the following Monday. Every machine, despite being reinstalled, would start its work-units right where it left off.
To archive your current Folding@Home progress, simply use:
sudo origami archive
This will archive its data in the format of $hostname-$date.tar.gz in ~/.origamirc/.
NETWORK-ARCHIVE
Origami facilitates archiving all network-managed Folding@Home clients with a single command. As outlined above in the Network Client Configuration section, hosts that are defined in the ~/.origamirc file can be managed remotely via SSH.
To archive all data, across all defined network hosts, simply run:
sudo origami network-archive
This will archive each machines current progress onto the "master" server, stored in ~/.origami/ as $hostname-$date.tar.gz
RESTORE
In the same way that Origami facilitates archival of current work progress, it easily allows for restoring the same data.
To restore your previous Folding@Home progress, simply use:
sudo origami restore
This will restore whatever data file it finds in ~/.origamirc/ matching the current hostname.
NETWORK-RESTORE
Origami allows you to restore previously archived data onto networked hosts using a single command. It should be mentioned that with archiving and restoration, due dates should be kept in mind.
To restore data to all network hosts, simply run:
sudo origami network-restore
This process scans the ~/.origami/ folder and attempts to connect to the same hostname(s) as defined in the archive filename.
ERASE
If you have decided you no longer want to contribute to the project, or simply need to remove your current installation to start fresh Origami makes this a simple process as well.
To erase all Folding@Home related data (with the exception of the origami script itself), simply run:
sudo origami erase
This removes all local work progress, init scripts, the origami user, and all configuration files.
ARMAGEDDON
This aptly named function removes all traces of Folding@Home from all network-connected hosts as defined in the ~/.origamirc. Please use this with caution as it will wipe out all data, settings and progress from both server and clients.
To destroy all Folding@Home data from all hosts, simply run:
sudo origami armageddon
NAME
Origami allows you to update your user and team information by calling the name function. If you never configured these values, or if you simply want to change them (perhaps you'd like to change teams), it is a simple update.
To update your name and team information (both paremeters required), simply run:
sudo origami name -u USERNAME -t TEAMNUMBER
While these values are instantly applied, you may not see the updates in the statistics until you finish your next work-unit.
NETWORK-NAME
Origami allows you to update your user and team information remotely by using the network management tools.
To remotely update your user name and team information (both parameters required), simply run:
sudo origami network-name -u USERNAME -t TEAMNUMBER
PROXY
If you need to update your proxy information, Origami makes this simple as well. In most cases defining a proxy isn't required; you'll know if you need proxy settings.
To update your proxy information, simply run:
sudo origami proxy -P port -H host
STATUS
Whether you've just started with Folding@Home or you're a long-time vetran of the project, you'll like want to check your current progress. Origami provides a simple interface that provides you with your current username, team, completed work-units (per processor), current assignment, and progress percentage.
To view your current status, simply run:
origami status
NETWORK-STATUS
Origami allows you to centrally monitor progress on all hosts. The output will be the same as the local function, one host at a time with a short pause in between each.
To view your current status on all hosts, simply run:
sudo origami network-status
STATISTICS
Origami provides a simple interface that pulls detailed user and team statistics from public stats servers. This data will allow you to see statistics such as: User and Team Ranking, 24hr Point Average, Rank Changes, Work Unit Completion, and much more.
To view your current user and team statistics, simply run:
origami stats
START
Origami provides a shortcut to starting (and stopping) your Folding@Home client. This command is a front-end to the same system that starts the Folding@Home client at boot-time, and allows you to turn off your client as needed.
To manually start your Folding@Home client, simply run:
sudo origami start
NETWORK-START
Origami allows you to remotely start (and stop) your Folding@Home clients over a secure connection. This option connects to all hosts defined in the ~/.origamirc file and starts the Folding@Home service.
To ensure the service is started on each host, simply run:
sudo origami start
STOP
Origami provides a shortcut to stopping (and starting) your Folding@Home client. This command is a front-end to the same system that stops the Folding@Home client at shutdown, and allows you to turn off your client as needed.
To manually stop your Folding@Home client, simply run:
sudo origami stop
NETWORK-STOP
Origami allows you to remotely stop (and start) your Folding@Home clients over a secure connection. This option connects to all hosts defined in the ~/.origamirc file and stops the Folding@Home service.
To ensure the service is stopped on each host, simply run:
sudo origami network-stop
AUTHORS
Origami was written by Christer Edwards. This manual page was written by Christer Edwards.
Both are released under the GNU General Public License, version 2 or later.
