Skip to content

Client configuration

Jump to bottom
David Anderson edited this page Nov 8, 2024 · 13 revisions

The BOINC client can be configured to control its behavior and to produce more detailed log messages. These messages appear in the Event Log of the BOINC Manager; they are also written to the file stdoutdae.txt (Windows) or to standard output (Unix).

There are three configuration mechanisms:

  • XML configuration files.
  • 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: square brackets in examples indicate optional parts. When using the example, don't include the square brackets.

Configuration files

There are several XML-format configuration files: cc_config.xml, nvc_config.xml, and (for each project) app_config.xml. If the file is absent, the default configuration is used. To create or edit a file, use a text editor such as Notepad, and save it in your BOINC Data directory or project directory.

General configuration

The cc_config.xml file has the format:

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

Options

The <options> section contains settings that control the behavior of the BOINC client. Default values will be used for any options not specified.

<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.

<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).

<alt_platform>platform_name</alt_platform>

Specify an alternate platform name, to be included in scheduler requests. You can specify more than one.

<coproc>
    <type>some_name</type>
    <count>1</count>
    [ <device_nums>0 2</device_nums> ]
    [ <peak_flops>1e10</peak_flops> ]
    [ <non_gpu/> ]
</coproc>

Specify a coprocessor, such as an FPGA or a GPU not known to BOINC (i.e. not NVIDIA, AMD, or Intel). The elements are:

<count>: the number of coprocessor instances.

<device_nums>: their device numbers (default 0, 1, ...).

<peak_flops> their the peak FLOPS (or IOPS for integer processors) per instance.

If <non_gpu/> is specified, the coprocessor is not treated as a GPU; e.g. "Suspend GPU" does not affect it.

You can use this in combination with the Anonymous platform mechanism, in which case the name given in <type> must match that in the <coproc> element in app_info.xml. Or projects can offer app versions that use the coprocessor, with an appropriate plan class specification. The coprocessor description is passed in scheduler RPC requests.

<device_name>NAME</device_name>

use the given name to identify this computer on project web sites. Default: network domain name.

<disallow_attach>0|1</disallow_attach>

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

<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. This flag also suppresses a periodic fetch of a project list from boinc.berkeley.edu.

<dont_suspend_nci>0|1</dont_suspend_nci>

If set, exempt non-CPU-intensive tasks from suspension in most cases.

<dont_use_vbox>0|1</dont_use_vbox>

If set, don't run VirtualBox jobs. Does not cancel already downloaded jobs.

<exclude_gpu>
    <url>project_URL</url>
    [<device_num>N</device_num>]
    [<type>NVIDIA|ATI|intel_gpu</type>]
    [<app>appname</app>]
</exclude_gpu>

Don't use the given GPU for the given project. <device_num>: specifies the number of the GPU to exclude (0..63). If not given, exclude all GPUs of the given type.

<type>: the GPU type. Can be omitted if your computer has only one type of GPU.

<app>: 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. If you want to exclude the GPU use for all projects, look at the <ignore_ati_dev>, <ignore_nvidia_dev> and <ignore_intel_dev> options below. Requires a client restart.

<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.

<exclusive_gpu_app>important.exe</exclusive_gpu_app>

BOINC will suspend use of GPUs whenever the executable is running.

<exit_before_start>0|1</exit_before_start>

Exit just before starting a task.

<exit_when_idle>0|1</exit_when_idle>

Exit when all tasks finished (see --exit_when_idle).

<fetch_minimal_work>0|1</fetch_minimal_work>

Fetch one job per device (see --fetch_minimal_work).

<fetch_on_update>0|1</fetch_on_update>

When updating a project, request work even if not highest priority project.

<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 (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.

<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.

<http_1_0>0|1</http_1_0>

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. Requires a client restart.

<ignore_intel_dev>N</ignore_intel_dev>

Ignore (don't use) a specific Intel GPU. Requires a client restart.

<ignore_nvidia_dev>N</ignore_nvidia_dev>

Ignore (don't use) a specific NVIDIA GPU. You can ignore more than one. Requires a client restart.

<ignore_tty>path</ignore_tty>

(Unix) Ignore TTY devices starting with 'path' in checking if the system is idle. By default, devices in /dev/tty*, /dev*, and /dev/pts/* are checked for activity.

<lower_client_priority>0|1</lower_client_priority>

If set, run the client in a mode where its CPU, disk, and memory usage has lower priority than other processes. Requires a client restart.

<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).

<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_overdue_days>X</max_overdue_days>

Abort jobs that are overdue by at least X days.

<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.

<max_stdout_file_size>N</max_stdout_file_size>

Specify the maximum size of the standard out log file (stdoutdae.txt) in bytes; default is 2 MB. 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.

<ncpus>N</ncpus>

Act as if there were N CPUs; e.g. to simulate 2 CPUs on a machine that has only 1. Zero means use the actual number of CPUs. Don't use this to limit CPU usage; use computing preferences instead.

<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.

<no_gpus>0|1</no_gpus>

If 1, don't use GPUs even if they're present. Requires a client restart.

<no_info_fetch>0|1</no_info_fetch>

If enabled, this prevents downloading version info, updating project list and notices from the BOINC server.

<no_opencl>0|1</no_opencl>

If 1, don't use OpenCL. Requires a client restart.

<no_priority_change>0|1</no_priority_change>

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

<no_rdp_check>0|1</no_rdp_check>

(Windows) if 1, allow GPU apps to run while using Remote Desktop Protocol (RDP). This requires that you configure RDP as described here: https://knowledge.civilgeo.com/knowledge-base/enabling-gpu-rendering-for-microsoft-remote-desktop/

<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.

<process_priority>N</process_priority>
<process_priority_special>N</process_priority_special>

The OS process priority at which tasks are run. Values are:

  • 0 (lowest priority, the default)
  • 1 (below normal)
  • 2 (normal)
  • 3 (high)
  • 4 (highest).

'Special' process priority is used for coprocessor (GPU) applications, wrapper applications, and non-compute-intensive applications, 'process priority' for all others. The two options can be used independently.

<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> ]
    [ <socks5_remote_dns>0|1</socks5_remote_dns> ] *
    [ <no_proxy>list of hostnames for which proxy not used</no_proxy> ]
    [ <no_autodetect>0|1</no_autodetect> ] *
</proxy_info>

Specify HTTP proxy settings.

<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.

<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 a 60 second delay from completion of result upload (normally it's deferred for up to one hour, 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.

<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.

<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.

<skip_cpu_benchmarks>0|1</skip_cpu_benchmarks>

Disable the periodic benchmark testing as well as block the 'run CPU benchmarks' from the manager menu.

<start_delay>nseconds</start_delay>

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

<suppress_net_info>0|1</suppress_net_info>

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.

<use_all_gpus>0|1</use_all_gpus>

If 1, use all GPUs (otherwise only the most capable ones are used). Requires a client restart.

<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.

<vbox_window>0|1</vbox_window>

If enabled, launch VirtualBox applications with an interactive console window. Otherwise, run them silently with VBoxHeadless.

Logging flags

The BOINC client writes "log messages" describing what it's doing. These are written to stdout, and to the BOINC Manager's "Event log". There are many types of messages; you can select which types to show.

NOTE: beginning with version 7.4.26, the BOINC Manager has a dialog for editing the logging options. This may be easier than editing the config file. Access this dialog by selecting ''Event Log Diagnostic Flags'' from the ''Advanced'' menu or by pressing ''CTRL+Shift+F'' simultaneously on the keyboard in either the Advanced View or the Simple View (''Command+Shift+F'' on a Macintosh.)

You can enable or disable each type in the <log_flags> section. For example, to see messages about CPU scheduling, edit cc_config.xml 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 section take effect only when you restart the BOINC client).

The flags within <log_flags> are used to selectively turn different types of messages on and off (0 for off, 1 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.

<async_file_debug>

Asynchronous copy and checksum of large (> 10 MB) files.

<benchmark_debug>

Debugging information about CPU benchmarks.

<checkpoint_debug>

Show when applications checkpoint.

<coproc_debug>

Show details of coprocessor (GPU) scheduling.

<cpu_sched>

CPU scheduler actions (preemption and resumption).

<cpu_sched_debug>

Explain CPU scheduler decisions.

<cpu_sched_status>

Show what tasks are running.

<dcf_debug>

For seeing changes in DCF.

<disk_usage_debug>

Show disk usage info.

<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.

<scrsave_debug>

Debugging information about the screen saver.

<slot_debug>

Prints messages about allocation of slots, creating/removing files in slot dirs.

<state_debug>

Show summary of client state after scheduler RPC and garbage collection

<statefile_debug>

Show when and why state file is written.

<suspend_debug>

Show details of processing and network suspend/resume.

<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.

<unparsed_xml>

Show any unparsed XML.

<work_fetch_debug>

Work fetch policy decisions.

Project-level configuration

You can specify scheduling parameters for specific applications or app versions. To do this, create a file app_config.xml in the project's directory, e.g. when the project is SETI@home: {BOINC Data directory}\projects\setiathome.berkeley.edu.

The file format:

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

The app name (in <name> and <app_name> elements) is case insensitive.

Each <app> element specifies parameters for a given application. Its elements are:

<name>

short name of the application as found in the corresponding <name>xxxxx</name> element in your client_state.xml file.

<max_concurrent>

The maximum number of tasks of this application to run at a given time.

<fraction_done_exact>

If set, base estimates of remaining time solely on the fraction done reported by the app.

<gpu_usage>

The number of GPU instances (possibly fractional) used by GPU versions of this app. For example, .5 means that two jobs of this application can run at once on a single GPU.

<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>. Its elements are:

<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.

<project_max_concurrent>

A limit on the number of running jobs for this project.

<report_results_immediately>

If set, report this project's completed tasks immediately.

If you remove app_config.xml, or change any of its entries, you must reset the project (or restart the client) in order to restore the proper values.

Branded-client configuration

The nvc_config.xml file contains up to four tags. This file is used mainly by ''branded'' clients to set special values used to determine and report whether there is a newer version available for download.

''Branded'' clients are custom builds of BOINC, usually distributed by Account_managers or projects. ''Branded'' builds usually also have an associated custom skin (see Creating_a_skin_for_the_BOINC_Manager.)

The nvc_config.xml file has the following format:

<nvc_config>
    [ ... ]
</nvc_config>

Changes to this file take effect only when you restart the BOINC client.

It can contain one or more of the following settings. (Prior to BOINC version 7.14, these tags (except <client_new_version_name>) were included in the ''options'' section of the cc_config.xml file.)

<client_download_url>URL</client_download_url>

The URL the user should visit to download the new client. Default is http://boinc.berkeley.edu/download_all.php.

<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.

<client_new_version_name>NAME</client_new_version_name>

The branded name of the client installer. Default is BOINC.

<network_test_url>URL</network_test_url>

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

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.

--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).

--allow_remote_gui_rpc

Allow GUI RPCs from remote hosts.

--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).

--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. Typically used in combination with --fetch_minimal_work.

--fetch_minimal_work

Fetch only enough jobs to use all device instances (CPU, GPU). Used with --exit_when_idle, the client will use all devices (possibly with a single multicore job), then exit when this initial set of jobs is completed.

--get_daily_xfer_history

Shows network traffic history.

--gui_rpc_port N

Specify port for GUI RPCs.

--help

Show client options.

--no_gui_rpc

Don't allow GUI RPCs. Consequently the client cannot be controlled by external tools like GUIs (boincmgr etc.) or the console command tool (boinccmd).

--no_gpus

Don't use GPUs.

--no_info_fetch

Prevents downloading version info, updating project list and notices from BOINC server.

--no_priority_change

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

--redirectio

redirect stdout and stderr to log files instead of terminal window.

--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.

--suppress_net_info

Don't send IP address and domain name to servers.

--version

Show client version.

Startup options

The following options cause the client to perform an action on startup. NOTE: these will fail if there's already a client running on this host. To control a running client, use the boinccmd tool.

--attach_project URL account_key

Attach this computer to a project. The account (which must already exist) is specified by account_key. Use --passw password (the password from gui_rpc_auth.cfg) on Linux and MacOS versions as well.

--detach_project URL

Detach this computer from a project.

--reset_project URL

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

--update_prefs URL

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

Debugging options

The following command-line options are for debugging:

--app_test filename

run the given executable in a special slot directory (slots/app_test).

--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

--stderr_head

report the first 64KB (rather than last 64KB) of job stderr to server.

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.

Home

Clone this wiki locally