Client configuration

From BOINC

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. BOINC does not use standard XML. Putting comments in the file will cause errors.

If you edit the configuration file while BOINC is running, the changes will take effect only if you select the Advanced / Read config file menu item.

Warning: Any changes in the <log_flags> section will be used immediately after re-read of the config file. Yet a lot of changes in the <options> section will need a complete exit and restart of the BOINC client. They will not take if you just re-read the config file.

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 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. 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.
<dcf_debug>: For seeing changes in DCF. New in 6.6
<disk_usage_debug>: Show disk usage info. New 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 debt.
<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.
<trickle_debug>: Details of trickles. New 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. New 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) New in 6.10.46.
<alt_platform>platform_name</alt_platform>: Specify an alternate platform name, to be included in scheduler requests. New 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. New 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. New in 6.3.15
<disallow_attach>0|1</disallow_attach>: If enabled, the client won't attach to new projects. New 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. 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

<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. New in 6.13

<exclude_gpu>
   <url>project_URL</url>
   [<device_num>N</device_num>]
   [<type>nvidia|ati</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. New in 6.3.13
<exclusive_gpu_app>important.exe</exclusive_gpu_app>: BOINC will suspend use of GPUs whenever the executable is running. New in 6.10.20
<exit_before_start>0|1</exit_before_start>: Exit just before starting a task. New in 6.13.3
<exit_when_idle>0|1</exit_when_idle>: Exit when all tasks finished (see --exit_when_idle). New in 6.11
<fetch_minimal_work>0|1</fetch_minimal_work>: Fetch one job per device (see --fetch_minimal_work). New in 6.11
<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 New 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 New 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 New 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. New 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. New in 6.10.19 and only to be used till 6.12.41.
<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/> New 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_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. New 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. 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!
<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. New in 6.12
<ncpus>N</ncpus>: Act as if there were N CPUs; 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 (was 0 which in newer clients really means zero to e.g. only allow GPU computing).
<network_test_url>URL</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>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. New in 5.9.10
<no_gpus>0|1</no_gpus>: If 1, don't use GPUs even if they're present. New 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). New 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. New in 5.10
<proxy_info>: Specify proxy settings. The element has the following form: New 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. New 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. New 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. New 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. New 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. New in 5.10
<use_all_gpus>0|1</use_all_gpus>: If 1, use all GPUs (otherwise only the most capable ones are used). New 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. New in 6.3.11

<zero_debts>0|1</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_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. New 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. New in 6.11
--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. New in 6.6.19
--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.
--stderr_head: report the first 64KB (rather than last 64KB) of job stderr to server New in 6.10.25.
--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

Client configuration

From BOINC

Contents

Configuration file

Logging flags

Options

Command-line options

Environment variables

Views

Personal tools

Resources

Contents

Search

Toolbox