Initialization files

From BOINC
Jump to: navigation, search

The behavior of the BOINC client (the core client and manager) can be influenced by various files (in the BOINC data directory) and web browser cookies. For example, these items can cause the client to attach to one or more projects, attach to an account manager, or attach to one project by default and allow the user to create an account.

You can include these items in custom installers to control the behavior of the resulting clients.

Files

Account files
Each one describes an attached project.
acct_mgr_url.xml
Contains the name and URL of an account manager.
acct_mgr_login.xml
Contains credentials (name/password) for the account manager identified in acct_mgr_url.xml.
client_brand.txt
Contains a client brand, e.g. "HTC Power to Give". Reported to and stored on servers.
project_init.xml
Specifies a project and optionally an account.

Web browser cookies

If acct_mgr_url.xml is present, the Manager may look for browser cookies name Logon, PasswordHash, and Signed from that URL. These cookies specify an account on the AMS.

If project_init.xml is present, the Manager may look for browser cookies named Setup and Signed from that URL. These cookies specify an account on the project.

Semantics

When the manager connects to the client it runs through a series of checks to determine if an attach wizard needs to be launched, and if so which attach wizard should be launched.

If the client is not attached to any projects an attach wizard must be launched.

If an acct_mgr_url.xml file is specified but a acct_mgr_logon.xml file is missing and the credentials are specified via browser cookies then the client attaches to the account manager with the credentials specified in the cookies.

If an acct_mgr_url.xml file is specified but a acct_mgr_logon.xml file is missing and no browser cookie is detected the attach to account manager wizard is launched and automatically advanced to the logon page. Once the credentials are specified the client attaches to the account manager.

If both the acct_mgr_url.xml and acct_mgr_logon.xml files exist the attach to account manager wizard is launched and the client is attached to the account manager.

If the project_init.xml file exists and the credentials exist within project_init.xml or via a browser cookie the client is attached to the specified project.

If the project_init.xml exists but no credentials exists the attach to project wizard is launched and advanced to the logon page.

If neither the acct_mgr_url.xml or project_init.xml files exist the attach to project wizard is launched from the beginning.

File formats

project_init.xml

<project_init>
    <url>PROJECT_URL</url>
    [ <name>PROJECT_NAME</name> ]
    [ <account_key>KEY</account_key> ]
    [ <team_name>TEAM_NAME</team_name> ]
</project_init>

Note: you should use the weak account keys to protect access to the account.

acct_mgr_url.xml

This file identifies the account manager. It is typically included in an installer package. Its format is:

<acct_mgr>
    <name>Name of BOINC account management system</name>
    <url>http://acctmgr.com/</url>
    [ <send_gui_rpc_info/> ]
    <signing_key>
1024
ae843acebd4c7250b0fa575d14971b17a56a386a6bb1733d98f4b00460c26159
c8b3217e6cdff938ec0454330c70553fbe3d1f0d0184d8c628db2e093121ee98
8ddbda6e8991879317afccab41f84e9de4903a656f4d3f3e4e7dbc0af9362a05
6ece5ff401a380f3a1d1254d477f7bc84fdcebcca6cb035e776452d3d6d21471
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000010001
.
    </signing_key>
</acct_mgr>

The URL is that of the account manager's web site.

Note: the easiest way to generate this file to attach to the project manager, and copy the resulting file in the BOINC data directory.

acct_mgr_login.xml

This file contains meta-account information. Its format is:

<acct_mgr_login>
   <login>name</login>
   <password_hash>xxx</password_hash>
</acct_mgr_login>

The easiest way to create this file is to attach a client to the project manager, and use the resulting file in the BOINC data directory.

Cookie details

The project’s web server drops a cookie on the user’s machine, typically during the sign-up process, called ‘SETUP’ when contains the user’s authenticator. This cookie should be set to expire within an hour or two. The cookie needs to be assigned to the same path as the projects URL.

Project cookie

Project Master URL:

http://www.worldcommunitygrid.org/

Cookie path:

www.worldcommunitygrid.org

Cookie name:

Setup

Cookie value:

cbad34855451e9927bc0fe46f47e4385

Cookie Name:

Signed

Cookie value:

<cookie>
<message>
<authenticator>cbad34855451e9927bc0fe46f47e4385</authenticator>
</message>
<signature>
huvhyucyhcygctgxygchcgctxgytgchchc
</signature>
</cookie>

NOTE: The signature block is the signed contents of the <message> block using the projects's public key. ||

Account Manager cookie

This process relies on the [AccountManagement#Coreclientfunctionality acct_mgr_url.xml] file being distributed as part of the installation process. The [AccountManagement#Coreclientfunctionality acct_mgr_url.xml] file contains the account manager’s name and URL.

The two pieces of information required to successfully attach to an account manager is the account logon name and password hash. As with the attach to project cookies, the account manager cookies should expire within an hour or two.

Here is an example on generating a password hash:

#!c++
string calculate_password_hash(logon_name, password) {

    // downcase the logon_name string
    string logon_name_lc = lowercase(logon_name);

    // generate md5 hash of the password and lower case logon_name
    string password_hash = md5sum(password+logon_name_lc);
    return password_hash;
}

The following cookies would be created by the account manager server:

Account Manager URL:

http://www.gridrepublic.org/

Cookie path:

www.gridrepublic.org

Cookie name:

Logon

Cookie value:

example@example.org

Cookie name:

PasswordHash

Cookie value:

cbad34855451e9927bc0fe46f47e4385

Cookie name:

ReturnURL

Cookie value:

http://www.example.org/return.php?id=765786547

Cookie Name:

Signed

Cookie value:

<cookie>
<message>
<logon>example@example.org</logon>
<password_hash>cbad34855451e9927bc0fe46f47e4385</password_hash>
[ <return_url>http://www.example.org/return.php?id=765786547</return_url> ]
</message>
<signature>
huvhyucyhcygctgxygchcgctxgytgchchc
</signature>
</cookie>

NOTE: The signature block is the signed contents of the <message> block using the account manager's public key.

Browsers Supported

At present the current browsers are supported:

  • Internet Explorer 3.x, 4.x, 5.x, 6.x, 7.x, 8.x
  • Safari 2.x, 3.x, 4.x
  • Firefox 2.x, 3.x