Client configuration

From BOINC
Jump to: navigation, search

Contents


The BOINC client can be configured to:

  • Control the behavior of the client.
  • Produce more detailed log messages. These messages appear in the Messages tab (6.10 and earlier) or Event Log (6.12 and later) of the BOINC Manager. They are also written to the file stdoutdae.txt (Windows) or to standard output (Unix).

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.

Note: Wherever you see square brackets [ ] used in the examples, these are not used. They show additional options. When using the specific piece of code, delete the square brackets, or the option you try to use will be ignored.

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.

Beginning with version 7.3.16, the BOINC Manager has a dialog to make it easier to edit the logging options. You can access this dialog by selecting Event Log Diagnostic Flags from the Advanced menu or by entering Control-Shift-F from the keyboard in either the Advanced View or the Simple View (Command-Shift-F on a Macintosh.) To view the output of the logging flags in BOINC Manager's Event Log window, select Event Log from the Advanced menu, or enter Control-Shift-E from the keyboard in either the Advanced View or the Simple View (Command-Shift-E on a Macintosh.)

This file has the following format:

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

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

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

If you edit the file while BOINC is running, the changes will take effect only if you select the Advanced / Read config file menu item. (Note: some changes in the <options> section take effect only when you restart the BOINC client).

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 debugging):

<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. List-add.pngNew in 5.8
<checkpoint_debug>
Show when applications checkpoint. List-add.pngNew in 5.10
<coproc_debug>
Show details of coprocessor (GPU) scheduling. List-add.pngNew in 6.3
<cpu_sched>
CPU scheduler actions (preemption and resumption).
<cpu_sched_debug>
Explain CPU scheduler decisions.
<dcf_debug>
For seeing changes in DCF. List-add.pngNew in 6.6
<disk_usage_debug>
Show disk usage info. List-add.pngNew in 7.0.4
<file_xfer_debug>
Show completion status of file transfers.
<gui_rpc_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).
<priority_debug>
Changes to project scheduling priority.
<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. List-add.pngNew 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 List-add.pngNew in 6.6.18.
<suspend_debug>
Show details of processing and network suspend/resume. List-add.pngNew in 7.0.27
<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.
<trickle_debug>
Details of trickles. List-add.pngNew in 6.13.6
<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>
If 1, abort jobs and update projects when client exits. Useful on grids where disk gets wiped after each run. List-add.pngNew in 6.6.10
<allow_multiple_clients>0|1</allow_multiple_clients>
allow multiple BOINC clients to run on a single host. Each must run in a different data directory.
<allow_remote_gui_rpc>0|1</allow_remote_gui_rpc>
If 1, allow GUI RPCs from any remote host (see Controlling BOINC remotely) List-add.pngNew in 6.10.46.
<alt_platform>platform_name</alt_platform>
Specify an alternate platform name, to be included in scheduler requests. List-add.pngNew in 5.10.26
<client_download_url>URL</client_download_url>
The URL to tell user to visit to download new client. Default is http://boinc.berkeley.edu/download_all.php. List-add.pngNew in 6.3.15
<client_version_check_url>URL</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. List-add.pngNew in 6.3.15
<coproc>
specify a GPU. Used in combination with the Anonymous platform mechanism. The element has the form
<coproc>
  <type>some_name</type>
  <count>1</count>
  <device_nums>0 2</device_nums>
  [ <peak_flops>1e10</peak_flops> ]
</coproc>
 
The name given in <type> must match that in the <coproc> element in app_info.xml. <count> in the number of GPU instances, and <device_nums> is their device numbers. <peak_flops> is the GPU peak FLOPS; it can be omitted if your app_info.xml specifies estimated application FLOPS. This mechanism has two purposes: to provide fine-grained control of the coprocessors recognized by BOINC (NVIDIA, AMD, and Intel GPUs), and to let you use coprocessors not recognized by BOINC.
<data_dir>path</data_dir>
Use the given directory as the BOINC data directory (default: current directory).
<disallow_attach>0|1</disallow_attach>
If enabled, the client won't attach to new projects. List-add.pngNew in 5.10
<dont_check_file_sizes>0|1</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.
<dont_contact_ref_site>0|1</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. List-add.pngNew in 5.10.14. This flag also suppresses a periodic fetch of a project list from boinc.berkeley.edu. List-add.pngNew in 5.10.31
<exclude_gpu>
 
Don't use the given GPU for the given project. If <device_num> is not specified, exclude all GPUs of the given type. <type> is required if your computer has more than one type of GPU; otherwise it can be omitted. <app> specifies the short name of an application (i.e. the <name> element within the <app> element in client_state.xml). If specified, only tasks for that app are excluded. You may include multiple <exclude_gpu> elements. If you change GPU exclusions, you must restart the BOINC client for these changes to take effect. List-add.pngNew in 6.13
<exclude_gpu>
   <url>project_URL</url>
   [<device_num>N</device_num>]
   [<type>NVIDIA|ATI|intel_gpu</type>]
   [<app>appname</app>]
</exclude_gpu>
<exclusive_app>filename.exe</exclusive_app>
BOINC will suspend computing whenever the executable is running (e.g., a game). Case is ignored in filenames. Multiple applications can be specified. List-add.pngNew in 6.3.13
<exclusive_gpu_app>important.exe</exclusive_gpu_app>
BOINC will suspend use of GPUs whenever the executable is running. List-add.pngNew in 6.10.20
<exit_before_start>0|1</exit_before_start>
Exit just before starting a task. List-add.pngNew in 6.13.3
<exit_when_idle>0|1</exit_when_idle>
Exit when all tasks finished (see --exit_when_idle). List-add.pngNew in 6.11
<fetch_minimal_work>0|1</fetch_minimal_work>
Fetch one job per device (see --fetch_minimal_work). List-add.pngNew in 6.11
<fetch_on_update>0|1</fetch_on_update>
When updating a project, request work even if not highest priority project. List-add.pngNew in 7.0.54
<force_auth>auth_method</force_auth>
When authenticating against a proxy server use a specific authentication method. Valid parameters are: basic, digest, gss-negotiate, ntlm List-add.pngNew in 5.10.41 (Setting of particular importance for World Community Grid to facilitate SSL/HTTPS communications)
<http_transfer_timeout>seconds</http_transfer_timeout>
abort HTTP transfers if idle for this many seconds; default 300 List-add.pngNew in 6.12.27
<http_transfer_timeout_bps>bps</http_transfer_timeout_bps>
an HTTP transfer is considered idle if its transfer rate is below this many bits per second List-add.pngNew in 6.12.27
<http_1_0>0|1</http_1_0>
Set this flag to use HTTP 1.0 instead of 1.1 (this may be needed with some proxies).
<ignore_ati_dev>N</ignore_ati_dev>
ignore (don't use) a specific ATI GPU. You can ignore more than one. List-add.pngNew in 6.10.19
<ignore_cuda_dev>N</ignore_cuda_dev>
ignore (don't use) a specific NVIDIA GPU. You can ignore more than one. List-add.pngNew in 6.10.19 and only to be used till 6.12.41.
<ignore_intel_dev>N</ignore_intel_dev>
ignore a specific Intel GPU.
<ignore_nvidia_dev>N</ignore_nvidia_dev>
ignore (don't use) a specific NVIDIA GPU. You can ignore more than one. Replaces <ignore_cuda_dev/> List-add.pngNew in 6.13.0
Reminder: Zero will disable device zero, it does not disable the line, only removal does. <ignore_nvidia_dev>1</ignore_nvidia_dev> will ignore the use of the second Nvidia GPU in the system.
Before 6.13.0, <ignore_cuda_dev/> was used. <ignore_nvidia_dev> was added to get it more in line with the specific <ignore_ati_dev>.
<max_event_log_lines>N</max_event_log_lines>
Maximum number of lines to display in BOINC Manager's Event Log window (default 2000, 0 means no limit). List-add.pngNew in 7.1.2
<max_file_xfers>N</max_file_xfers>
Maximum number of simultaneous file transfers (default 8).
<max_file_xfers_per_project>N</max_file_xfers_per_project>
Maximum number of simultaneous file transfers per project (default 2).
<max_stderr_file_size>N</max_stderr_file_size>
Specify the maximum size of the standard error log file (stderrdae.txt); default is 2 MB. List-add.pngNew in 5.10.28
<max_stdout_file_size>N</max_stdout_file_size>
Specify the maximum size of the standard out log file (stdoutdae.txt); default is 2 MB. List-add.pngNew 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!
<max_tasks_reported>N</max_tasks_reported>
report at most N tasks per scheduler RPC. Try N=1000 if your computer has lots of tasks to report and is having trouble completing a scheduler RPC. List-add.pngNew in 6.12
<ncpus>N</ncpus>
Act as if there were N CPUs; e.g. to simulate 2 CPUs on a machine that has only 1. To use the number of available CPUs, set the value to -1 (was 0 which in newer clients really means zero).
<network_test_url>URL</network_test_url>
The URL to use when checking network connectivity; default is http://www.google.com/. List-add.pngNew in 6.3.15
<no_alt_platform>0|1</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. List-add.pngNew in 5.9.10
<no_gpus>0|1</no_gpus>
If 1, don't use GPUs even if they're present. List-add.pngNew in 6.6
<no_priority_change>0|1</no_priority_change>
If 1, don't change priority of applications (run them at same priority as client). List-add.pngNew in 6.6.18
NB: This option can, if activated, impact system responsiveness for the user. Default, all CPU science apps run at lowest (idle) priority Nice 15.
<os_random_only>0|1</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. List-add.pngNew in 5.10
<proxy_info>
Specify proxy settings. The element has the following form: List-add.pngNew in 6.6.12
<proxy_info>
    [ <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>
<rec_half_life_days>X</rec_half_life_days>
A project's scheduling priority is determined by its estimated credit in the last X days. Default is 10; set it larger if you run long high-priority jobs. List-add.pngNew in 6.13.1
<report_results_immediately>0|1</report_results_immediately>
If 1, 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. This is intended to be used only on computers whose disks are reformatted daily. List-add.pngNew in 6.1
<run_apps_manually>0|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. List-add.pngNew in 6.1.7
<save_stats_days>N</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>0|1</simple_gui_only>
If enabled, the BOINC Manager will display only the simple GUI.
<start_delay>nseconds</start_delay>
Specify a number of seconds to delay running applications after client startup. List-add.pngNew in 6.1.6
<suppress_net_info>0|1</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. List-add.pngNew in 5.10
<use_all_gpus>0|1</use_all_gpus>
If 1, use all GPUs (otherwise only the most capable ones are used). List-add.pngNew in 6.6.25
<use_certs>0|1</use_certs>
Accept applications signed using X509 certificates, as well as those that have BOINC signatures.
<use_certs_only>0|1</use_certs_only>
Accept only applications signed with X509 certificates. List-add.pngNew in 6.3.11
<zero_debt>0|1</zero_debt>
Resets inter-project debts. Intended to be applied one time, then tag set back to 0 before next client restart or reread of config file. (Deprecated from version 7)

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. List-add.pngNew 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). List-add.pngNew 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_console
Detach from console (Windows only; Linux equivalent is --daemon, see above).
--detach_project URL
Detach this computer from a project.
--dir abs_path
Use the given directory as BOINC home.
--exit_when_idle
Exit when there are no more tasks, and report completed tasks immediately. List-add.pngNew in 6.1
--fetch_minimal_work
Fetch only 1 job per device (CPU, GPU). Used with --exit_when_idle, the client will process one job per device, then exit. List-add.pngNew in 6.11
--get_daily_xfer_history
Shows network traffic history. List-add.pngNew in 6.10.13
--gui_rpc_port N
Specify port for GUI RPCs.
--help
Show client options.
--no_gui_rpc
Don't allow GUI RPCs.
--no_gpus
Don't use GPUs. List-add.pngNew in 6.6.19
--no_priority_change
Don't change priority of applications (run them at same priority as client). List-add.pngNew 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. List-add.pngNew in 6.1
--stderr_head
report the first 64KB (rather than last 64KB) of job stderr to server. List-add.pngNew in 6.10.25
--suppress_net_info
Don't send IP address and domain name to servers. List-add.pngNew in 7.0.53
--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).
--file_xfer_giveup_period N
Specify giveup period for file transfers
--skip_cpu_benchmarks
Don't run CPU benchmarks

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.

Application configuration

This mechanism allows you to specify scheduling parameters associated with specific applications or app versions. It is available with 7.0.40+ client versions.

To do this, create a file app_config.xml in the project's directory, e.g. when the project is Seti: {BOINC Data directory}\projects\setiathome.berkeley.edu\
Use the following format:

<app_config>
   [<app>
      <name>uppercase</name>
      <max_concurrent>1</max_concurrent>
      <gpu_versions>
          <gpu_usage>.5</gpu_usage>
          <cpu_usage>.4</cpu_usage>
      </gpu_versions>
    </app>]
   ...
   [<app_version>
       <app_name>uppercase</app_name>
       [<plan_class>mt</plan_class>]
       [<avg_ncpus>x</avg_ncpus>]
       [<ngpus>x</ngpus>]
       [<cmdline>--nthreads 7</cmdline>]
   </app_version>]
   ...
</app_config>

All the tags use lowercase characters. The app_name may contain uppercase characters.
Each <app> element specifies parameters for a given application:

name
short name of the application as found in the appropriate <name>xxxxx</name> tags in your client_state.xml file. The name is in lower case characters (the 'uppercase' in the above is an example of the application name).
max_concurrent
The maximum number of tasks of this application to run at a given time.
gpu_usage
The number of GPU instances (possibly fractional) used by GPU versions of this app.
cpu_usage
The number of CPU instances (possibly fractional) used by GPU versions of this app.

Each <app_version> element specifies parameters for a given app version; it overrides <app>. List-add.pngNew in 7.2.39


app_name
the short name of the application.
plan_class
the plan class of the app version.
avg_ncpus
the number of CPU instances (possibly fractional) used by the app version.
ngpus
the number of GPU instances (possibly fractional) used by the app version.
cmdline
command-line parameters to pass to the program.
Personal tools