Project options

The following elements in the <config> section of your config.xml file control various aspects of your project.

Scheduling options and parameters

[ <one_result_per_user_per_wu/> ]
[ <max_wus_to_send> N </max_wus_to_send> ]
[ <max_wus_in_progress> N </max_wus_in_progress> ]
[ <min_sendwork_interval> N </min_sendwork_interval> ]
[ <daily_result_quota> N </daily_result_quota> ]
[ <ignore_delay_bound/> ]
[ <dont_generate_upload_certificates/> ]
[ <ignore_upload_certificates/> ]
[ <locality_scheduling/> ]
[ <locality_scheduling_wait_period> N </locality_scheduling_wait_period> ]
[ <min_core_client_version> N </min_core_client_version> ]
[ <choose_download_url_by_timezone> 0|1 </choose_download_url_by_timezone> ]
[ <cache_md5_info> 0|1 </cache_md5_info> ]
[ <nowork_skip> 0|1 </nowork_skip> ]
[ <resend_lost_results> 0|1 </resend_lost_results> ]
[ <send_result_abort>0|1</send_result_abort> ]
[ <default_disk_max_used_gb> X </default_disk_max_used_gb> ]
[ <default_disk_max_used_pct> X </default_disk_max_used_pct> ]
[ <default_disk_min_free_gb> X </default_disk_min_free_gb> ]
[ <one_result_per_host_per_wu/> ]
[ <next_rpc_delay>x</next_rpc_delay> ]
[ <workload_sim>0|1</workload_sim> ]
[ <shmem_work_items>N</shmem_work_items> ]
[ <feeder_query_size>N</feeder_query_size> ]
[ <homogeneous_redundancy>N</homogeneous_redundancy> ]
[ <ended>0|1</ended> ]
[ <ban_os>regexp</ban_os> ]
[ <ban_cpu>regexp</ban_cpu> ]
[ <max_ncpus>N</max_ncpus> ]
[ <granted_credit_weight>X</granted_credit_weight> ]
[ <granted_credit_ramp_up>N</granted_credit_ramp_up> ]
[ <distinct_beta_apps>0|1</distinct_beta_apps> ]

one_result_per_user_per_wu

If present, send at most one result of a given workunit to a given user. This is useful for checking accuracy/validity of results. It ensures that the results for a given workunit are generated by different users. If you have a validator that compares different results for a given workunits to ensure that they are equivalent, you should probably enable this. Otherwise you may end up validating results from a given user with results from the same user.

max_wus_to_send

Maximum results sent per scheduler RPC. Helps prevent hosts with trouble from getting too many results and trashing them. But you should set this large enough so that a host which is only connected to the net at intervals has enough work to keep it occupied in between connections.

max_wus_in_progress

Maximum results in progress per CPU. Setting this to something (like 2 for instance) will limit the number of results a given host can simultaneously have registered as 'in progress'.

min_sendwork_interval

Minimum number of seconds to wait after sending results to a given host, before new results are sent to the same host. Helps prevent hosts with download or application problems from trashing lots of results by returning lots of error results. But don't set it to be so long that a host goes idle after completing its work, before getting new work.

daily_result_quota

Maximum number of results (per CPU) sent to a given host in a 24-hour period. Helps prevent hosts with download or application problems from returning lots of error results. Be sure to set it large enough that a host does not go idle in a 24-hour period, and can download enough work to keep it busy if disconnected from the net for a few days. The maximum number of CPUS is bounded at four.

ignore_delay_bound

By default, results are not sent to hosts too slow to complete them within delay bound. If this flag is set, this rule is not enforced.

dont_generate_upload_certificates

Don't put upload certificates in results. This makes result generation a lot faster, since no encryption is done, but you lose protection against DoS attacks on your upload servers.

ignore_upload_certificates

If upload certificates are not generated, this option must be enabled to force file upload handler accept files being uploaded.

locality_scheduling

When possible, send work that uses the same files that the host already has. This is intended for projects which have large data files, where many different workunits use the same data file. In this case, to reduce download demands on the server, it may be advantageous to retain the data files on the hosts, and send them work for the files that they already have. See Locality Scheduling.

locality_scheduling_wait_period

This element only has an effect when used in conjunction with the previous locality scheduling element. It tells the scheduler to use 'trigger files' to inform the project that more work is needed for specific files. The period is the number of seconds which the scheduler will wait to see if the project can create additional work. Together with project-specific daemons or scripts this can be used for 'just-in-time' workunit creation. See Locality Scheduling.

min_core_client_version

If the scheduler gets a request from a client with a version number less than this, it returns an error message and doesn't do any other processing. The version number is expressed as an integer with the encoding major*100+minor. You can also specify this separately for each application.

choose_download_url_by_timezone

When the scheduler sends work to hosts, it replaces the download URL appearing in the data and executable file descriptions with the download URL closest to the host's timezone. The project must provide a two-column file called 'download_servers' in the project root directory. This is a list of all download servers that will be inserted when work is sent to hosts. The first column is an integer listing the server's offset in seconds from UTC. The second column is the server URL in the format such as http://einstein.phys.uwm.edu. The download servers must have identical file hierarchies and contents, and the path to file and executables must start with '/download/...' as in 'http://X/download/123/some_file_name'.

cache_md5_info

When creating work, keep a record (in files called foo.md5) of the file length and md5 sum of data files and executables. This can greatly reduce the time needed to create work, if (1) these files are re-used, and (2) there are many of these files, and (3) reading the files from disk is time-consuming.

nowork_skip

If the scheduling server has no work, it replies to RPCs without doing any database access (e.g., without looking up the user or host record). This reduces DB load, but it fails to update preferences when users click on Update. Use it if your server DB is overloaded.

resend_lost_results

If set, and a <other_results> list is present in scheduler request, resend any in-progress results not in the list. This is recommended; it may increase the efficiency of your project. For reasons that are not well understood, a BOINC client sometimes fails to receive the scheduler reply. This flag addresses that issue: it causes the SAME results to be resent by the scheduler, if the client has failed to receive them. Note: this will increase the load on your DB server; you can minimize this by creating an index:

alter table result add index res_host_state (hostid, server_state);

send_result_abort

If set, and the client is processing a result for a WU that has been canceled or is not in the DB (i.e. there's no chance of getting credit), tell the client to abort the result regardless of state. If client is processing a result for a WU that has been assimilated or is overdue (i.e. there's a chance of not getting credit) tell the client to abort the result if it hasn't started yet. Note: this will increase the load on your DB server.

default_disk_max_used_gb

Sets the default value for the disk_max_used_gb preference so it's consistent between the scheduler and web pages. The scheduler uses it when a request for work doesn't include preferences, or the preference is set to zero. The web page scripts use it to set the initial value when displaying or editing preferences the first time, or when the user never saved them. Default is 100.

default_disk_max_used_pct

Sets the default value for the disk_max_used_pct preference so its consistent between the scheduler and web pages. The scheduler uses it when a request for work doesn't include preferences, or the preference is set to zero. The web page scripts use it to set the initial value when displaying or editing preferences the first time, or when the user never saved them. Default is 50.

default_disk_min_free_gb

Sets the default value for the disk_min_free_gb preference so its consistent between the scheduler and web pages. The scheduler uses it when a request for work doesn't include preferences. The web page scripts use it to set the initial value when displaying or editing preferences the first time, or when the user never saved them. Also, the scheduler uses this setting to override any smaller preference from the host, it enforces a 'minimum free disk space' to keep from filling up the drive. Recommend setting this no smaller than .001 (1MB or 1,000,000 bytes). Default is .001.

reliable_max_avg_turnaround, reliable_max_error_rate

Hosts whose average turnaround is at most reliable_max_avg_turnaround and whose error rate is at most reliable_max_error_rate are considered 'reliable'.

reliable_reduced_delay_bound

When a result is sent to a reliable host, multiply the delay bound by reliable_reduced_delay_bound (typically 0.5 or so).

reliable_on_priority, reliable_on_over, reliable_on_over_except_error

Results with priority at least 'reliable_on_priority' will be sent only to reliable hosts; increase priority of duplicate results by 'reliable_priority_on_over'; increase priority of duplicates caused by timeout (not error) by 'reliable_priority_on_over_except_error'.

one_result_per_host_per_wu

If present, send at most one result of a given workunit to a given host. This is weaker than one_result_per_user_per_wu; it is useful if you're using homogeneous redundancy and most of the hosts of a particular class belong to a single user.

next_rpc_delay

In each scheduler reply, tell the clients to do another scheduler RPC after at most X seconds, regardless of whether they need work. This is useful, e.g., to ensure that in-progress jobs can be canceled in a bounded amount of time.

workload_sim

Do a simulation, based on current client workload, in deciding whether a job's deadline can be met.

shmem_work_items

The size of the shared-memory array of jobs. Default is 100.

feeder_query_size

The size of the feeder's enumeration query. Default is 200.

homogeneous_redundancy

If zero (default) don't use the homogeneous redundancy mechanism. Otherwise, specifies the granularity of host classification (1=fine, 2=coarse).

ended

Project has permanently ended. Tell clients so user can be notified.

ban_os

Any host for which os_name<tab>os_version matches the given regular expression will not be sent jobs. This is a POSIX extended regular expression.

ban_cpu

Any host for which p_vendor<tab>p_model matches the given regular expression will not be sent jobs. This is a POSIX extended regular expression.

max_ncpus

Treat all hosts as having no more than N CPUs. This affects things like max results per day. Use this, e.g., if your application uses a GPU or other co-processor.

granted_credit_weight

KEVIN - PLEASE EXPLAIN

distinct_beta_apps

If set, user application selection applies to beta test applications as well as others.

Deprecated options

<no_darwin_6>1</no_darwin_6>

Don't issue work to Macintoshes with Darwin 6 or earlier (Mac OS X 10.2 or earlier). Equivalent to

<ban_os>.*Darwin.*\t.*(5\.|6\.).*</ban_os>

<no_amd_k6>1</no_amd_k6>

Don't issue work to clients with AMD K6 processors. Equivalent to

<ban_cpu>.*AMD.*\t.*Family 5 Model 8 Stepping 0.*</ban_cpu>

Client control

[ <verify_files_on_app_start/> ]
[ <symstore>URL</symstore> ]
[ <min_core_client_version_announced> N </min_core_client_version_announced> ]
[ <min_core_client_upgrade_deadline> N </min_core_client_upgrade_deadline> ]
[ <msg_to_host/> ]
[ <non_cpu_intensive> 0|1 </non_cpu_intensive> ]

verify_files_on_app_start

Before starting or restarting an app, check contents of input files and app version files by either MD5 or digital signature check. Detects user tampering with file (but doesn't really increase security, since user could also change MD5s or signatures in client state file).

symstore

URL of your project's symbol store, used for debugging Windows applications.

min_core_client_version_announced

Announce a new version of the BOINC core client, which in the future will be the minimum required version. In conjunction with the next tag, you can warn users with version below this to upgrade by a specified deadline. Example value: 419.

min_core_client_upgrade_deadline

Use in conjunction with the previous tag. The value given here is the Unix epoch returned by time(2) until which hosts can update their core client. After this time, they may be shut out of the project. Before this time, they will receive messages warning them to upgrade.

msg_to_host

If present, check the msg_to_host table on each RPC, and send the client any messages queued for it.

non_cpu_intensive

If this flag is present, the project will be treated specially by the client:

• The client will download one result at a time.
• This result will be executed whenever computation is enabled (bypassing the normal scheduling mechanism).

This is intended for applications that use little CPU time, e.g. that do network or host measurements.

Server logging

[ <sched_debug_level> N </sched_debug_level> ]
[ <fuh_debug_level> N </fuh_debug_level> ]

sched_debug_level

Verbosity level for scheduler log output. 1=minimal, 2=normal (default), 3=verbose.

fuh_debug_level

Verbosity level for file upload handler log output. 1=minimal, 2=normal (default), 3=verbose.

The following boolean options enable various types of debugging output:

debug_version_select

Explain app version selection.

debug_assignment

Explain the sending of assigned work.

debug_prefs

Show the propagation of global prefs.

debug_send

Explain the sending of jobs.

debug_request_headers

Show HTTP request headers.

debug_user_messages

Show messages we're sending to the user.

debug_request_details

Show details of request message.

debug_handle_results

Show the handling of reported jobs.

Credit

(See also the command-line options of the validator).

[ <fp_benchmark_weight> X </fp_benchmark_weight> ]

fp_benchmark_weight

The weighting given to the Whetstone benchmark in the calculation of claimed credit. Must be in [0 .. 1]. Projects whose applications are floating-point intensive should use 1; pure integer applications, 0. Choosing an appropriate value will reduce the disparity in claimed credit between hosts. The script html/ops/credit_study.php, run against the database of a running project, will suggest what value to use.

File deletion policy

[ <delete_delay_hours>X</delete_delay_hours> ]
[ <httpd_user>username</httpd_user> ]

delete_delay_hours

Wait X hours before deleting files. This provides a 'grace period' during which late results will still get credit.

httpd_user

The user name under which the web server runs. As a safeguard, the file deleter skips files not owned by this user.

Server status page options

[ <www_host>hostname</www_host> ]
[ <sched_host>hostname</sched_host> ]
[ <uldl_host>hostname</uldl_host> ]
[ <uldl_pid>path</uldl_pid> ]
[ <ssh_exe>path</ssh_exe> ]
[ <ps_exe>path</ps_exe> ]

www_host

Host name of web server.

sched_host

Host name of scheduling server.

uldl_host

Host name of upload/download server.

uldl_pid

pid file of upload/download server (default: /etc/httpd/run/httpd.pid).

ssh_exe

path to ssh (default: /usr/bin/ssh).

ps_exe

path to ps (which supports "w" flag) (default: /bin/ps).

Web site features

[ <profile_screening/> ]
[ <show_results/> ]
[ <no_forum_rating/> ]
[ <akismet_key> 1234567890ab </akismet_key> ]
[ <users_per_page>N</users_per_page> ]
[ <teams_per_page>N</teams_per_page> ]
[ <hosts_per_page>N</hosts_per_page> ]
[ <recaptcha_public_key>X</recaptcha_public_key> ]
[ <recaptcha_private_key>X</recaptcha_private_key> ]
[ <profile_min_credit>X</profile_min_credit> ]
[ <team_forums_members_only>0|1</team_forum_members_only> ]
[ <moderators_vote_to_ban>0|1</moderators_vote_to_ban> }

profile_screening

If present, don't show profile pictures until they've been screened and approved by project admins.

show_results

Enable web site features that show results (per user, host, etc.)

no_forum_rating

Disable forum post rating.

akismet_key

If set, akismet.com is used to check post contents to protect forums from spam. See Protecting message boards from spam for more information.

users/teams/hosts_per_page

Number of entries per page for top users/teams/hosts. Default is 20.

recaptcha public/private keys

Enable the use of Recaptcha for profile creation/editing; see Protecting message boards from spam for more information.

profile_min_credit

The minimum amount of credit to create or edit a profile.

team_forums_members_only

If set, team message boards are visible only to team members.

moderators_vote_to_ban

If set, banishments require a majority vote among moderators.

Miscellaneous

[ <disable_account_creation/> ]
[ <min_passwd_length> N </min_passwd_length> ]

disable_account_creation

If present, disallow account creation.

min_passwd_length

Minimum length of user passwords. Default is 6.

request_time_stats_log

If nonzero, the scheduler will tell clients (via scheduler replies) to upload (via scheduler requests) their time stats log (which contains records of when the client started and stopped running).

Hosts, directories, and URLs

(These are created by make_project; normally you don't need to change them.)

<master_url>            URL                   </master_url>
<long_name>             name                  </long_name>
<host>                  project.hostname.ip   </host>
<db_name>               databasename          </db_name>
<db_host>               database.host.ip      </db_host>
<db_user>               database_user_name    </db_user>
<db_passwd>             database_password     </db_passwd>
<shmem_key>             shared_memory_key     </shmem_key>
<download_url>          http://A/URL          </download_url>
<download_dir>          /path/to/directory    </download_dir>
<uldl_dir_fanout>       N                     </uldl_dir_fanout>
<upload_url>            http://A/URL          </upload_url>
<upload_dir>            /path/to/directory    </upload_dir>
<cgi_url>               http://A/URL          </cgi_url>
<log_dir>               /path/to/directory    </log_dir>
<!-- optional; defaults as indicated: -->
    <bin_dir>      bin      </bin_dir>      <!-- relative to project_dir -->
    <cgi_bin_dir>  cgi-bin  </cgi_dir>      <!-- relative to project_dir -->
[ <sched_lockfile_dir> path </sched_lockfile_dir> ]

host

name of project's main host, as given by Python's socket.hostname(). Daemons and tasks run on this host by default.

db_name

Database name.

db_host

Database host machine.

db_user

Database user name.

db_passwd

Database password.

shmem_key

ID of scheduler shared memory. Must be unique on host.

download_url

URL of data server for download.

download_dir

absolute path of download directory.

download_dir_alt

absolute path of old download directory (see upload/download directories).

upload_url

URL of file upload handler.

uldl_dir_fanout

fan-out factor of upload and download directories (see Hierarchical upload/download directories).

upload_dir

absolute path of upload directory.

cgi_url

URL of scheduling server.

log_dir

absolute path of logfile directory.

sched_lockfile_dir

Enables scheduler locking (recommended) and specifies directory where scheduler lockfiles are stored. Must be writable to the Apache user.

Parsing project options

A program or script can access project options as follows:

• C/C++: use the SCHED_CONFIG class (sched/sched_config.C,h)
• PHP: use the get_config() and parse_config() functions in inc/util.inc
• scripts: use the bin/parse_config program