Boinccmd tool

From BOINC

The program boinccmd provides a command-line interface to a running BOINC client, local or remote. This is an alternative to the BOINC Manager, e.g. on systems with no graphics display.

The usage of boinccmd is:

boinccmd [--host hostname] [--passwd passwd] command

If you run boinccmd in the same directory as the BOINC client, you don't need to supply either a host name or a password.

Otherwise you need to supply (as password) the string stored in the file gui_rpc_auth.cfg in the client's data directory. If you run boinccmd remotely you also need to configure the client to accept remote control.

hostname can be a domain name, an IPv4 address, or an IPv6 address. If the client uses a non-default GUI RPC port, you can specify it as hostname:port, IPv4_addr:port, or [IPv6_addr]:port.

If you use the bash shell, you may find this command completion script useful.

Account query and attach

--lookup_account URL email password
Look up account on the given project, and if present print the account key.
--create_account URL email password name
Create account with the given email address, password, and user name.
--project_attach URL account_key
Attach to an account

Account manager operations

--acct_mgr info
show current account manager info. List-add.pngNew in 7.10
--acct_mgr attach URL name password
attach to an account manager. List-add.pngNew in 7.10
--acct_mgr sync
synchronize with (via an RPC) the current account manager. List-add.pngNew in 7.10
--acct_mgr detach
detach from the current account manager. List-add.pngNew in 7.10
--join_acct_mgr URL name password
same as "--acct_mgr attach".
--quit_acct_mgr
same as "--acct_mgr detach".

State queries

--get_cc_status
Show CPU/GPU/network run modes and network connection status (version 6.12+)
--get_state
Show complete client state
--get_tasks
Show tasks
--get_task_summary {pcedsrw}
Show tasks (1 task per line). Options: List-add.pngNew in 7.24
  • p: project name
  • c: completion %
  • e: elapsed time
  • d: deadline
  • s: status
  • r: resource usage
  • w: WU name
--get_old_tasks
Show reported tasks from last 1 hour (not 24 hours as shown in online help)
--get_simple_gui_info
Show projects and active tasks
--get_file_transfers
Show file transfers
--get_project_status
Show status of all projects
--get_project_urls
List URLs of attached projects, one per line
--get_disk_usage
Show disk usage by project
--get_proxy_settings
Get proxy settings
--get_messages seqno
Show messages with sequence numbers beyond the given seqno
--get_host_info
Show host info
--version, -V
Show core client version

Control operations

--task URL task_name operation {--window_station ws} {--desktop dt} {--display dp}
Do operation on a task, identified by the project master URL and the task name. operations:
  • suspend: temporarily stop work on task
  • resume: allow work on task
  • abort: permanently stop work on task
  • graphics_window: open graphics in a window. The optional desktop/window_station (Windows) or display (X11) arguments specify the display.
  • graphics_fullscreen: open graphics fullscreen
--project URL operation
Do operation on a project, identified by its master URL. Operations:
  • reset: delete current work and get more;
  • detach: delete current work and don't get more;
  • update: contact scheduling server;
  • suspend: stop work for project;
  • resume: resume work for project;
  • nomorework: finish current work but don't get more;
  • allowmorework: undo nomorework
  • detach_when_done: detach project
--file_transfer URL filename {retry | abort}
Do operation on a file transfer
--set_run_mode {always | auto | never} [ duration ]
Set run mode.
  • always: do CPU work always
  • auto: do work only when allowed by preferences
  • never: don't do work

If duration is zero or absent, this mode is permanent. Otherwise, after 'duration' seconds elapse, revert to last permanent mode.

--set_gpu_mode {always | auto | never} [ duration ]
Set GPU mode. Like set_run_mode but applies to GPU computation.
--set_network_mode {always | auto | never} [ duration ]
Set network mode. Like set_run_mode but applies to network transfers
--set_proxy_settings http_server_name http_server_port http_user_name http_user_passwd socks_server_name socks_server_port socks_version socks5_user_name socks5_user_passwd
Set proxy settings (all fields are mandatory). List-add.pngNew in 6.6.12 (exists but doesn't work before 6.6.12).
--run_benchmarks
Run CPU benchmarks
--set_screensaver_mode on|off blank_time {--desktop desktop} {--window_station window_station} {--display display}
Tell the core client to start or stop doing fullscreen graphics, and going to black after blank_time seconds. The optional arguments specify which desktop/windows_station (Windows) or display (X11) to use.
--read_global_prefs_override
Tell the core client to read the [PrefsOverride global_prefs_override.xml] file, and incorporate any global preferences indicated there.
--quit
Tell the core client to quit
--read_cc_config
Reread the configuration files, to include any app_config.xml existing in the project folders. (cc_config.xml).

Miscellaneous

--help, -h
Show options and commands

Examples

It's not hard to write useful scripts based on boinccmd, as long as you know your way around Unix tools. Here's one to run 'update' on all attached projects on your client:

for url in $(boinccmd --get_project_status | sed -n 's/\s*master URL: //p'); do
  boinccmd --project ${url} update;
done

If you have remote RPCs set up on your clients, you can attach a project on all 50 machines by looping over a list of IPs:

for num in $(seq 2 50); do
    boinccmd --host 192.168.42.${num} --passwd 1234 \
    --project_attach http://project_url/ a84dc0bec631cbf81e25e6e7cd9ca826;
done;

That will connect to the machines 192.168.42.2 - 192.168.42.50 using the RPC password '1234' and make them attach to http://project_url/ with the specified account key.

Command completion for boinccmd

The BASH shell has a useful facility to complete commands when you press `[Tab]`. There is a [source:boinc/client/scripts/boinc.bash script] which goes a bit further and lets BASH complete [UnixClientPackage boinc's] and [userw:Boinccmd_tool boinccmd's] commands and options.

For example if you type `boinccmd --get_[Tab]` it gives you all commands which begin with `--get_`:

~$ boinccmd --get_
--get_cc_status            --get_project_status
--get_disk_usage           --get_proxy_settings
--get_file_transfers       --get_results
--get_host_info            --get_screensaver_mode
--get_messages             --get_simple_gui_info
--get_project_config       --get_state
--get_project_config_poll

If you now press `p` and then `[Tab]` again the selection is reduced to:

~$ boinccmd --get_pro
--get_project_config       --get_project_status
--get_project_config_poll  --get_proxy_settings

and so on. The script also completes host names after the `--host` option.

To use this command completion, save [source:boinc/client/scripts/boinc.bash this script] on a file (e.g. `boinc.bash`) and source it in bash:

~$ source boinc.bash