Client configuration

From BOINC

The BOINC client can be configured to:

• Produce more detailed log messages. These messages appear in the Messages tab of the BOINC Manager (informational messages in black, error messages in red). On Windows, they are written to a file (stdoutdae.txt). On Unix, they are written to standard output.
• Control parameters such as how many simultaneous file transfers to allow.

There are three configuration mechanisms:

• An XML configuration file
• Command-line options (mainly for Unix)
• Environment variables (mainly for Unix)

Some parameters can be controlled using different mechanisms; pick the one that's best for you.

Contents 1 Configuration file 1.1 Logging flags 1.2 Options 2 Command-line options 3 Environment variables

Configuration file

The configuration is read from a file cc_config.xml. If this file is absent, the default configuration is used. To create or edit the file, use a text editor such as Notepad, and save it as cc_config.xml in your BOINC data directory.

This file has the following format:

<cc_config>
   <log_flags>
       [ ... ]
   </log_flags>
   <options>
       [ ... ]
   </options>
</cc_config>

For example, if you want to see messages about CPU scheduling, then edit the file so that it contains:

<cc_config>
   <log_flags>
       <cpu_sched>1</cpu_sched>
   </log_flags>
</cc_config>

Logging flags

The flags within <log_flags> are used to selectively turn different types of messages on and off (<tag>0</tag> for off, <tag>1</tag> for on): The following messages are enabled by default:

<task>

The start and completion of compute jobs (should get two messages per job).

<file_xfer>

The start and completion of file transfers.

<sched_ops>

Connections with scheduling servers.

The following messages are disabled by default (typically they generate lots of output, and are used for specific debugging purposes):

<app_msg_receive>

Shared-memory messages received from applications.

<app_msg_send>

Shared-memory messages sent to applications.

<benchmark_debug>

Debugging information about CPU benchmarks. New in 5.8

<checkpoint_debug>

Show when applications checkpoint. New in 5.10

<coproc_debug>

Show details of coprocessor (GPU) scheduling New in 6.3

<cpu_sched>

CPU scheduler actions (preemption and resumption).

<cpu_sched_debug>

Explain CPU scheduler decisions.

<debt_debug>

Changes to project debt.

<file_xfer_debug>

Show completion status of file transfers.

<guirpc_debug>

Debugging information about GUI RPC operations.

<http_debug>

Debugging information about HTTP operations.

<http_xfer_debug>

Debugging information about network communication.

<mem_usage_debug>

Application memory usage.

<network_status_debug>

Network status (whether need physical connection).

<poll_debug>

Show what poll functions do.

<proxy_debug>

Debugging information about HTTP proxy operations.

<rr_simulation>

Results of the round-robin simulation used by CPU scheduler and work-fetch.

<sched_op_debug>

Details of scheduler RPCs; also shows deferral intervals and other low info. New in 5.10.24

<scrsave_debug>

Debugging information about the screen saver.

<state_debug>

Show summary of client state after scheduler RPC and garbage collection

<statefile_debug>

Show when and why state file is written New in 6.6.18.

<task_debug>

Low-level details of process start/end (status codes, PIDs etc.), and when applications checkpoint.

<time_debug>

Updates to on_frac, active_frac, connected_frac.

<unparsed_xml>

Show any unparsed XML.

<work_fetch_debug>

Work fetch policy decisions.

Options

The following options control the behavior of BOINC:

[ <abort_jobs_on_exit>0|1</abort_jobs_on_exit> ]
[ <alt_platform>platform_name</alt_platform> ]
[ <client_download_url>URL</client_download_url> ]
[ <client_version_check_url>URL</client_version_check_url> ]
[ <disallow_attach>0|1</disallow_attach> ]
[ <dont_check_file_sizes>0|1</dont_check_file_sizes> ]
[ <dont_contact_ref_site>0|1</dont_contact_ref_site> ]
[ <exclusive_app>important.exe</exclusive_app> ]
[ <force_auth>auth_method</force_auth> ]
[ <http_1_0>0|1</http_1_0> ]
[ <max_file_xfers>N</max_file_xfers> ]
[ <max_file_xfers_per_project>N</max_file_xfers_per_project> ]
[ <max_stdout_file_size>N</max_stdout_file_size> ]
[ <max_stderr_file_size>N</max_stderr_file_size> ]
[ <ncpus>5</ncpus> ]
[ <network_test_url>URL</network_test_url> ]
[ <no_alt_platform>0|1</no_alt_platform> ]
[ <no_gpus>0|1</no_gpus> ]
[ <no_priority_change>0|1</no_priority_change> ]
[ <os_random_only>0|1</os_random_only> ]
[ <proxy_info> ... ]
[ <report_results_immediately>0|1</report_results_immediately> ]
[ <run_apps_manually>0|1</run_apps_manually> ]
[ <save_stats_days>N</save_stats_days> ]
[ <simple_gui_only>0|1</simple_gui_only> ]
[ <start_delay>nseconds</start_delay> ]
[ <suppress_net_info>0|1</suppress_net_info> ]
[ <use_all_gpus>0|1</use_all_gpus> ]
[ <use_certs>0|1</use_certs> ]
[ <use_certs_only>0|1</use_certs_only> ]
[ <zero_debts>0|1</zero_debts> ]

<abort_jobs_on_exit>

If 1, abort jobs and update projects when client exits. Useful on grids where client gets wiped after each run. New in 6.6.10

<alt_platform>

Specify an alternate platform name, to be included in scheduler requests. New in 5.10.26

<client_download_url>

The URL to tell user to visit to download new client. Default is http://boinc.berkeley.edu/download_all.php. New in 6.3.15

<client_version_check_url>

The URL to go to for XML list of client version. Default is http://boinc.berkeley.edu/download_all.php?xml=1. New in 6.3.15

<disallow_attach>

If enabled, the client won't attach to new projects. New in 5.10

<dont_contact_ref_site>

To determine if a physical network connection exists, the client occasionally contacts a highly-available web site (google.com). If this flag is set, this behavior is suppressed. New in 5.10.14. This flag also suppresses a periodic fetch of a project list from boinc.berkeley.edu. New in 5.10.31

<dont_check_file_sizes>

Normally, the size of application and input files are compared with the project-supplied values after the files are downloaded, and just before starting an application. If this flag is set, this check is skipped. Use it if you need to modify files locally for some reason.

<exclusive_app>

BOINC will suspend computing whenever the executable is running (e.g., a game). Multiple applications can be specified. New in 6.3.13

<force_auth>

When authenticating against a proxy server use a specific authentication method. Valid parameters are: basic, digest, gss-negotiate, ntlm New in 5.10.41 (Setting of particular importance for World Community Grid to facilitate SSL/HTTPS communications)

<http_1_0>

Set this flag to use HTTP 1.0 instead of 1.1 (this may be needed with some proxies).

<max_file_xfers>

Maximum number of simultaneous file transfers (default 8).

<max_file_xfers_per_project>

Maximum number of simultaneous file transfers per project (default 2).

<max_stderr_file_size>

Specify the maximum size of the standard error log file (stderrdae.txt); default is 2 MB. New in 5.10.28

<max_stdout_file_size>

Specify the maximum size of the standard out log file (stdoutdae.txt); default is 2 MB. New in 5.10.28

Sample: <max_stdout_file_size>3145728</max_stdout_file_size> equals 3 MB.

NB: A Client restart may be needed to have changes take effect!

<ncpus>

Act as if there were N CPUs: run N tasks at once. This is for debugging, i.e. to simulate 2 CPUs on a machine that has only 1. To use the number of available CPUs, set the value to -1. Don't use it to limit the number of CPUs used by BOINC; use general preferences instead.

<network_test_url>

The URL to use when checking network connectivity; default is http://www.google.com/. New in 6.3.15

<no_alt_platform>

If enabled, the client will run applications only for its primary platform. For example, a Win64 machine will run only Win64 apps, and not Win32. New in 5.9.10

<no_priority_change>

If 1, don't change priority of applications (run them at same priority as client). New in 6.6.18

<os_random_only>

If enabled, the client will use only OS-level functions to generate a random GUI RPC password, and will exit if these functions fail. Without this flag, if OS secure random functions aren't available, the client will fall back to a random-string generator based on time of day, free disk space, and other host-specific information. New in 5.10

<proxy_info>

Specify proxy settings. The element has the following form: New in 6.6.12

<proxy_info>
    <use_http_proxy>0|1</use_http_proxy>
    <use_http_auth>0|1</use_http_auth>
    <use_socks_proxy>0|1</use_socks_proxy>
    [ <http_server_name></http_server_name> ]
    [ <http_server_port>80</http_server_port> ]
    [ <http_user_name></http_user_name> ]
    [ <http_user_passwd></http_user_passwd> ]
    [ <socks_version>5</socks_version> ]
    [ <socks_server_name></socks_server_name> ]
    [ <socks_server_port>80</socks_server_port> ]
    [ <socks5_user_name></socks5_user_name> ]
    [ <socks5_user_passwd></socks5_user_passwd> ]
    [ <no_proxy>list of hostnames for which proxy not used</no_proxy> ]
</proxy_info>

<report_results_immediately>

If set, each job will be reported to the project server as soon as it's finished, with an inbuild 60 second delay from completion of result upload. (normally it's deferred for up to a day, so that several jobs can be reported in one request). Using this option increases the load on project servers, and should generally be avoided. It's intended to be used on computer whose disks are reformatted every day. New in 6.1

<run_apps_manually>

This is for debugging apps. When running an app, the client will do everything except actually run the app, i.e. it will set up the slot dir, create the shared mem segment, etc. It will then continue as if the app were actually running, and you can then manually run your app under a debugger in the slot directory. Note: the client won't notice the termination of your app. New in 6.1.7

<save_stats_days>

How many days to save the per-project credit totals that are displayed in the Statistics tab of the BOINC Manager. Default is 30.

<simple_gui_only>

If enabled, the BOINC Manager will display only the simple GUI.

<start_delay>

Specify a number of seconds to delay running applications after client startup. New in 6.1.6

<suppress_net_info>

If enabled, don't send this host's IP address and domain name to servers. Otherwise, this information is sent to, and stored on, servers. It is visible to you (but not other users) via the web. New in 5.10

<use_all_gpus>

If 1, use all GPUs (otherwise only the most capable ones are used). New in 6.6.25

<use_certs>

Accept applications signed using X509 certificates, as well as those that have BOINC signatures.

<use_certs_only>

Accept only applications signed with X509 certificates. New in 6.3.11

<no_gpus>

If 1, don't use GPUs even if they're present. New in 6.6

NB: A Client restart be needed to have changes take effect!

<zero_debts>

Set resource scheduling debts to zero. This lets you fix situations where client bugs have resulted in distorted debt values. Set it, run the client, then clear it (otherwise you'll start out with zero debts every time you run the client). New in 6.6.11

Command-line options

The BOINC client has the following command-line options. More detailed control, and the ability to interact with a running client, is provided by the boinccmd tool.

--abort_jobs_on_exit

Abort jobs and update projects when client exits. Useful on grids where client is wiped after each run. New in 6.6.10

--allow_multiple_clients

Allow multiple BOINC clients to run concurrently on a single host. If set, you must run each BOINC client in a separate BOINC data directory (if you run multiple clients in the same directory, this will not be detected, and mayhem will ensue). New in 6.2.2

--allow_remote_gui_rpc

Allow GUI RPCs from remote hosts

--attach_project URL account_key

Attach this computer to a new project.

--check_all_logins

(Unix) If 'run if user active' preference is off, check for input activity on all current logins; default is to check only local mouse/keyboard

--daemon

Linux: detach from controlling terminal; Windows: run as service

--detach

Detach from console (Windows only; Linux equivalent is --daemon, see below)

--detach_project URL

Detach this computer from a project.

--dir abs_path

Use the given directory as BOINC home

--gui_rpc_port N

Specify port for GUI RPCs

--help

Show client options.

--no_gui_rpc

Don't allow GUI RPCs.

--no_priority_change

Don't change priority of applications (run them at same priority as client). New in 6.6.18

--reset_project URL

Clear pending work for a project. Use this if there is a problem that is preventing your computer from working.

--run_cpu_benchmarks

Run CPU benchmarks. Do this if you have modified your computer's hardware.

--show_projects

Print a list of projects to which this computer is attached.

--start_delay N

Specify a number of seconds to delay running apps after client startup New in 6.1.

--update_prefs URL

Contact a project's server to obtain new preferences. This will also report completed results and get new work if needed.

--version

Show client version.

The following command-line options are for debugging:

--exit_after_app_start N

Exit about N seconds after first application starts

--exit_after_finish

Exit just after finishing any job (use this to check the contents of slot directories).

--exit_before_start

Exit just before starting any job (use this to check the contents of slot directories).

--exit_when_idle

Exit when 1) at least one scheduler request has been made, and 2) there are no more jobs, i.e. when all jobs have been completed, reported, and acknowledged. New in 6.1 Also causes results to be reported immediately after completion.

--file_xfer_giveup_period N

Specify giveup period for file transfers

--min

Put client in the background after starting up

--no_time_test

Don't run performance benchmarks; used fixed numbers instead.

--skip_cpu_benchmarks

Don't run CPU benchmarks

--started_by_screensaver

Passed by screensaver when it launches client

Environment variables

HTTP_PROXY

URL of HTTP proxy

HTTP_USER_NAME

User name for proxy authentication

HTTP_USER_PASSWD

Password for proxy authentication

SOCKS4_SERVER

URL of SOCKS 4 server

SOCKS5_SERVER

URL of SOCKS 5 server

SOCKS5_USER

User name for SOCKS authentication

SOCKS5_PASSWD

Password for SOCKS authentication