Boinccmd tool
Contents
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. New in 7.10
- --acct_mgr attach URL email password
- attach to an account manager. New in 7.10
- --acct_mgr sync
- synchronize with (via an RPC) the current account manager. New in 7.10
- --acct_mgr detach
- detach from the current account manager. New 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: New 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). New 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