Account Managers

This document describes BOINC's support for 'account managers' (AMs), which can streamline the process of finding and joining BOINC projects.

An AM provides a 'level of indirection' between volunteers and projects. Instead of attaching the BOINC client directly to projects, the volunteer attaches it to an AM account. The client then periodically issues an RPC to the AM, obtaining a list of project accounts. It then attaches to those accounts, and fetches jobs from the projects.

Attaching to an AM

A volunteer can attach a BOINC client to an AM account using the Tools / Use Account Manager command in the BOINC Manager. This brings up a dialog where they can choose a "vetted" AM (currently BAM!, GridRepublic, and Science United) and enter the account credentials. They can also enter the URL of a non-vetted AM.

Vetted AMs can optionally support the simplified registration/download process, where new volunteers can download the BOINC installer directly from the AM, and the attachment is done automatically during the install.

Project accounts

There are two approaches to project accounts:

BAM! and GridRepublic create separate project accounts for each volunteer. These accounts have the same email address and password as the AM account. This gives volunteers an identity on each account, at the cost of putting private data on each project.
Science United uses a single "anonymous" account on each project.

URL-signing

If hackers break into an AM server, they could potentially cause the AM to instruct all its clients to attach to a BOINC project that runs a malicious application. To prevent this type of attack, the URLs distributed by an AM are digitally signed. Each AM has its own signing key pair. The public key is distributed with the AM's configuration file and in all RPC replies. The private key should be stored only on a physically secure, non-connected host that is used to sign URLs.

To sign URLs, compile crypt_prog, BOINC's encryption utility program. Generate a key pair and generate signatures for your URLs. At some point you'll need to commit to a permanent key pair, at which point you should move the private key to the signing machine (disconnected). Make a copy or two on CD-ROM also, and/or print it out on paper; keep these in a safe place. Delete all other copies of the private key.

Support for farm managers

The AM mechanism can be used to implement systems for configuring and controlling BOINC on large clusters. We call such systems 'farm managers'. Farm managers may want to provide fine-grained control over clients, e.g. the ability to suspend/resume results. This can be done using GUI RPCs (assuming that the farm manager able to contact clients via HTTP on the GUI RPC port). However, the farm manager must learn the GUI RPC port and password for each client. To support this, the AM configuration file (see below) can specify that the GUI RPC port and password are to be included in each AM RPC request.

If a farm manager uses GUI RPC to attach/detach projects, it should not use the AM mechanism for this purpose. I.e., its AM RPC replies should not list any projects. The function of the AM mechanism, in this case, is to allow sysadmins to set up new clients by copying files. The AM mechanism takes care of registering new clients centrally.

Account manager RPCs

An account manager must provide a get_project_config.php file containing its name and minimum password length, and containing a <account_manager/> tag.

In addition, an account manager must provide the following RPC, which uses an HTTP POST request.

URL

BASE_URL/rpc.php, where BASE_URL is the URL of the AM.

input

<acct_mgr_request>
    <name>John</name>
    <password_hash>xxx</password_hash>
    <host_cpid>b11ddc5f36c9a86ff093c96e6930646a</host_cpid>
    <previous_host_cpid>b11ddc5f36c9a86ff093c96e6930646a</previous_host_cpid>
    <domain_name>host.domain</domain_name>
    <client_version>5.3.2</client_version>
    <run_mode>auto</run_mode>
<working_global_preferences>
<global_preferences>
   <run_on_batteries>0</run_on_batteries>
   <run_if_user_active>1</run_if_user_active>
   ... [ global preferences ]
</global_preferences>
</working_global_preferences>
    <global_preferences>
        <source_project>http://a.b.c</source_project>
        <source_scheduler>http://a.b.c</source_scheduler>
        <mod_time>1144105331</mod_time>
        ... [ global preferences ]
    </global_preferences>
    <host_info>
        ...
        <coprocs>
        <coproc_cuda>
		    ...
        </coproc_cuda>
        </coprocs>
    </host_info>
    <project>
       <url>http://setiathome.berkeley.edu/</url>
       <project_name>SETI@home</project_name>
       <suspended_via_gui>0|1</suspended_via_gui>
       <account_key>397d250e02ec02be8141b8d109d5ec73e5</account_key>
       <hostid>NNN</hostid>
       <not_started_dur>X</not_started_dur>
       <in_progress_dur>X</in_progress_dur>
       <attached_via_acct_mgr>0|1</attached_via_acct_mgr>
       <dont_request_more_work>0|1</dont_request_more_work>
       <detach_when_done>0|1</detach_when_done>
       <ended>0|1</ended>
    </project>
    [ ... other projects ]
    [ <gui_rpc_port>N</gui_rpc_port> ]
    [ <gui_rpc_password>xxxx</gui_rpc_password> ]
    [ <opaque>
         ... arbitrary XML
    </opaque> ]
    ...
</acct_mgr_request>

Two sets of global preferences are included. The one enclosed in <working_global_preferences> is the one currently in effect on the client; it includes local modifications (overrides) to the web-based preferences.

output

<acct_mgr_reply>
    [
     <error_num>N</error_num>
     <error_msg>xxx</error_msg>
    ]
    <name>Account Manager Name</name>
    <signing_key>
1024
ae843acebd4c7250b0fa575d14971b17a56a386a6bb1733d98f4b00460c26159
c8b3217e6cdff938ec0454330c70553fbe3d1f0d0184d8c628db2e093121ee98
8ddbda6e8991879317afccab41f84e9de4903a656f4d3f3e4e7dbc0af9362a05
6ece5ff401a380f3a1d1254d477f7bc84fdcebcca6cb035e776452d3d6d21471
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000010001
.
    </signing_key>
    [ <message>this is a message</message> ]
    [ ... ]
    [ <error>MSG</error> ]
    [ <repeat_sec>xxx</repeat_sec> ]
    [ <no_project_notices>0|1</no_project_notices> ]
    [
    <global_preferences>
        [ <source_project>http://a.b.c</source_project> ]
        [ <source_scheduler>http://a.b.c</source_scheduler> ]
        <mod_time>1144105331</mod_time>
        ... [ global preferences ]
    </global_preferences>
    ]
    [ <host_venue>venue</host_venue> ]
    [ <opaque>
         ... arbitrary XML
    </opaque> ]
    [
    <account>
       <url>URL</url>
       <url_signature>
397d250e02ec02be8141b8d196a118d909d5ec73e592ed50f9d0ad1ce5bf87de
e37f48079db76128b20f913a04e911489330a7cab8c346177f1682d236bc7201
42b32665d0d83474bf12aebd97b2bb9a4c4461fa3f0b49bbd40ecfa16715ced7
f72103eb0995be77cac54f253c0ba639a814d3293646ae11894e9d1367a98790
.
       </url_signature>
       <authenticator>KEY</authenticator>
       [ <update>0|1</update> ]
       [ <detach>0|1</detach> ]
       [ <suspend>0|1</suspend> ]
       [ <abort_not_started>0|1</abort_not_started> ]
       [ <dont_request_more_work>0|1</dont_request_more_work> ]
       [ <detach_when_done>0|1</detach_when_done> ]
       [ <resource_share>X</resource_share> ]
       [ <no_cpu>0|1</no_cpu> ]
       [ <no_cuda>0|1</no_cuda> ]
       [ <no_ati>0|1</no_ati> ]
       [ <no_rsc>RSC_NAME</no_rsc> ]
    </account>
    ...
    ]
    [
    <rss_feeds>
        <rss_feed>
            <url>http://news.google.com/news?cf=all&ned=us&hl=en&topic=s&output=rss</url>
            <poll_interval>60</poll_interval>
        </rss_feed>
    </rss_feeds>
    ]
    [
    <user_keywords>
        <yes>13</yes>
        ...
        <no>27</no>
        ...
    </user_keywords>
    ]
</acct_mgr_reply>

action

Returns a list of the accounts associated with this meta-account. The arguments are:

password_hash: the account password, hashed as MD5(password_lowercase(name)).
host_cpid: Identifies the host.
previous_host_cpid: The host identifier passed in the previous RPC. Host identifiers can change occasionally. This lets the account manager maintain host identity.
domain_name: The host's domain name.
run mode: The current mode (always/auto/never).
gui_rpc_port, gui_rpc_password: GUI RPC information. Included only if the <send_gui_rpc_info> element is included in the AM URL file (see above).
global_preferences: The current global preferences.
host_info: A description of the host's hardware and software (6.12.7+)
venue: The host venue
opaque: Opaque data received from the AMS in the previous RPC.
no_project_notices: If nonzero, suppress the display of notices from projects (but still display notices from the account manager). 7.0.65+.
projects: A list of currently attached projects. For each project:
url: the project's master URL
name: the project's name
account_key: the user's account key on this project
hostid: the host's database ID with this project
not_started_dur: Estimated duration (elapsed time) of unstarted jobs (6.12.7+)
in_progress_dur: Estimated duration (elapsed time) of jobs in progress (6.12.7+)
suspended_via_gui: whether project is suspended (via GUI or by the AM)
attached_via_acct_mgr: whether this project is attached via account manager (6.12.7+)
dont_request_more_work: whether work fetch is suspended for this project (6.12.7+)
detach_when_done: whether project is set to be detached when done (6.12.7+)
ended: whether project has ended (6.12.7+)

The return values are:

repeat_sec: A time interval after which another RPC should be done.
signing_key: The public key used to sign URLs, in an encoded notation. Use the BOINC crypt_prog program to generate this.
message: A message to be displayed to the user.
global_preferences: New global preferences. Included only if these are newer than those in the request message.
opaque: Arbitrary XML. Will be included in the next request message from the client. Use this e.g. to store a host ID.
rss_feeds: A list of RSS feeds to be displayed as Notices by the BOINC Manager. Typically this is a feed of news items from the account manager.
account: An account to which the client should attach. For each account, the following items are returned:
url: The project URL
url_signature: A signature for the URL. Use the BOINC crypt_prog program to generate this.
authenticator: The account's authenticator. This may be a strong or weak authenticator. NOTE: don't send weak authenticators to pre-6.13 clients; if the user changes their password, the weak authenticator changes, and pre-6.13 clients are not able to handle this. It's OK to send weak authenticators to 6.13+.
detach: If nonzero, the client should detach this project.
update: If nonzero, the client should contact this project to get new global preferences.
dont_request_more_work: If nonzero, don't request any more work from this project.
detach_when_done: If nonzero, detach from this project when all work is completed
suspend: suspend this project (6.12.7+)
abort_not_started: abort unstarted jobs for this project (6.12.7+)
resource_share: Specifies a resource share for this project. If present, this overrides the resource share reported by the project. Thus, account managers can provide per-host control of resource share.
no_cpu, no_cuda, no_ati: If set, don't fetch CPU/NVIDIA/ATI jobs from this project. Send these to 6.12.8+ client. For 7.0+ clients, these elements are deprecated, and have been replaced by
<no_rsc>RSC_NAME</no_rsc>: RSC_NAME is CPU, NVIDIA, ATI, or intel_gpu.
user_keywords: lists of keywords for which user preferences are Yes or No.

NOTE: the XML must be as above, with the <url> and <authenticator> elements on a single line, and the <account> and </account> tags on separate lines.

Home