United BOINC

!

The BOINC command tool (boinccmd, previously called boinc_cmd) provides a command-line interface to a running BOINC core client. boinccmd has the following interface:

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 use the bash shell, you may find this command completion script useful.

Core client connection

--host hostname[:port]

The host to connect to (default: localhost)

--passwd

The password for RPC authentication (default: boinccmd will look for a file gui_rpc_auth.cfg and use the password it contains).

Account query and attach

--lookup_account URL email password

Look up account and print account key. **New in 5.8.16** (see Old lookup_account for instructions on older versions)

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

--join_acct_mgr URL` name password

Attach to an account manager (or do RPC if already attached). **New in 5.10** (use --acct_mgr_rpc in versions older than 5.10).

--quit_acct_mgr

Detach from the current account manager. **New in 5.10**

State queries

--get_state

Show complete client state

--get_results

Show results

--get_simple_gui_info

Show projects and active results

--get_file_transfers

Show file transfers

--get_project_status

Show status of all projects

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

--result URL result_name operation {--window_station ws} {--desktop dt} {--display dp}

Do operation on a result, identified by the project master URL and the result name. operations:

• suspend: temporarily stop work on result
• resume: allow work on result
• abort: permanently stop work on result
• 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_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)

--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 file (cc_config.xml)

--set_debts URL1 STD1 LTD1 {URL2 STD2 LTD2 ...}

Set the short- and long-term debts of one or more projects. Note: if you adjust the debts of a project, the debts of other projects are changed, so if you want to set the debts of multiple projects, do it in a single command. **New in 5.10.14**

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, it's easy to, for example, attach a project on all 50 machines, by looping over a list of IPs instead of a list of projects:

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.

Old lookup_account

On versions 5.8.15 and older, attaching a project with an email and password is harder.

First, run:

./boinccmd --lookup_account http://project_url/ <email address> <password> 

This will not print your account key directly; it will probably show "retval: 0". Then run:

./boinccmd --lookup_account_poll 

It should print your account key (authenticator) for the project. If it doesn't, wait a few seconds and run it again; maybe the client didn't finish contacting the project yet. Once you get your account key, you can attach with:

./boinccmd --project_attach http://project_url/ <account key> 

Of course, you can also use --project_attach directly if you already know your account key