Changes between Version 8 and Version 9 of AccountManagement


Ignore:
Timestamp:
Nov 25, 2010, 10:45:22 PM (14 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AccountManagement

    v8 v9  
    1212    * Go through the Attach to Project wizard.
    1313
    14 If the participant chooses N projects, there are N web sites to visit and N Wizards to complete. This is tedious if there are lots of projects.
     14If the participant chooses N projects, there are N web sites to visit and N Wizards to complete.
     15This is tedious if there are lots of projects.
    1516
    1617This document describes BOINC's support for 'account management systems',
     
    1920A typical account management system is implemented as a web site. The participant experience is:
    2021
    21     * Visit the account manager site, set up a 'meta-account' (name, email, password), browse a list of projects, and click checkboxes to select projects.
     22    * Visit the account manager site, set up a 'meta-account' (name, email, password),
     23          browse a list of projects, and click checkboxes to select projects.
    2224    * Download and install the BOINC client software from the account manager.
    2325    * Enter the meta-account name and password in a BOINC client dialog.
     
    3335   1. The participant sets up his meta-account and selects projects.
    3436   2. The account manager issues a create account RPC to each selected project.
    35    3. the participant downloads and installs the BOINC client software from the account manager. The install package includes a file (specific to the account manager) containing the URL of the account manager.
     37   3. the participant downloads and installs the BOINC client software from the account manager.
     38      The install package includes a file (specific to the account manager) containing the URL of the account manager.
    3639   4. The BOINC client runs, and asks the participant to enter the name and password of his meta-account.
    37    5. The BOINC client does an RPC to the account manager, obtaining a list of accounts. It then attaches to these accounts and proceeds.
     40   5. The BOINC client does an RPC to the account manager, obtaining a list of accounts.
     41      It then attaches to these accounts and proceeds.
    3842
    3943There are [WebRpc web RPCs] to create, look up, and modify accounts.
     
    4145== Security ==
    4246
    43 If hackers break into an account manager server, they could potentially cause the account manager to instruct all its clients to attach to malicious a BOINC project that runs a malicious application. To prevent this type of attack, the URLs distributed by an account manager 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.
    44 
    45 To sign URLs, compile [KeySetup 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.
     47If hackers break into an account manager server,
     48they could potentially cause the account manager to instruct all its clients
     49to attach to malicious a BOINC project that runs a malicious application.
     50To prevent this type of attack, the URLs distributed by an account manager are digitally signed.
     51Each AM has its own signing key pair.
     52The public key is distributed with the AM's configuration file and in all RPC replies.
     53The private key should be stored only on a physically secure,
     54non-connected host that is used to sign URLs.
     55
     56To sign URLs, compile [KeySetup crypt_prog], BOINC's encryption utility program.
     57Generate a key pair and generate signatures for your URLs.
     58At some point you'll need to commit to a permanent key pair,
     59at which point you should move the private key to the signing machine (disconnected).
     60Make a copy or two on CD-ROM also, and/or print it out on paper; keep these in a safe place.
     61Delete all other copies of the private key.
    4662
    4763== Farm managers ==
    4864
    49 The AM mechanism can also 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.
    50 
    51 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.
    52 
    53 == Core client functionality ==
    54 
    55 The BOINC core client uses the following files to keep track of account manager information.
     65The AM mechanism can also be used to implement systems for configuring and controlling BOINC on large clusters.
     66We call such systems 'farm managers'.
     67Farm managers may want to provide fine-grained control over clients, e.g. the ability to suspend/resume results.
     68This can be done using GUI RPCs (assuming that the farm manager able to
     69contact clients via HTTP on the GUI RPC port).
     70However, the farm manager must learn the GUI RPC port and password for each client.
     71To support this, the AM configuration file (see below) can specify that
     72the GUI RPC port and password are to be included in each AM RPC request.
     73
     74If a farm manager uses GUI RPC to attach/detach projects, it should not use the AM mechanism for this purpose.
     75I.e., its AM RPC replies should not list any projects.
     76The function of the AM mechanism, in this case, is to allow sysadmins to set up new clients by copying files.
     77The AM mechanism takes care of registering new clients centrally.
     78
     79== Client functionality ==
     80
     81The BOINC client uses the following files to keep track of account manager information.
    5682
    5783
    5884acct_mgr_url.xml
    59     This file identifies the account manager. It is typically bundled with the BOINC client in an installer package. Its format is:
     85    This file identifies the account manager.
     86        It is typically bundled with the BOINC client in an installer package.
     87        Its format is:
    6088{{{
    6189<acct_mgr>
     
    79107    The URL is that of the account manager's web site.
    80108
    81     If the <send_gui_rpc_info/> tag is present, account manager RPCs will include the client's GUI RPC port and password hash (see below).
     109    If the <send_gui_rpc_info/> tag is present,
     110        account manager RPCs will include the client's GUI RPC port and password hash (see below).
    82111acct_mgr_login.xml
    83112    This file contains meta-account information. Its format is:
     
    90119The password is stored as MD5(password_lowercase(login)).
    91120
    92 If the core client finds acct_mgr_url.xml but not acct_mgr_login.xml, it prompts for a name and password, stores them in acct_mgr_login.xml, and makes an account manager RPC. The core client offers menu items for making an account manager RPC, and for changing the name/password.
     121If the client finds acct_mgr_url.xml but not acct_mgr_login.xml,
     122it prompts for a name and password, stores them in acct_mgr_login.xml, and makes an account manager RPC.
     123The client offers menu items for making an account manager RPC, and for changing the name/password.
    93124
    94125== Account manager RPCs ==
    95126
    96 An account manager must provide a [WebRpc#get_project_config get_project_config.php] file containing its name and minimum password length, and containing a <account_manager/> tag.
     127An account manager must provide a [WebRpc#get_project_config get_project_config.php] file
     128containing its name and minimum password length, and containing a <account_manager/> tag.
    97129
    98130In addition, an account manager must provide the following RPC, which uses an HTTP POST request.
     
    110142    <client_version>5.3.2</client_version>
    111143    <run_mode>auto</run_mode>
     144        <not_started_dur>X</not_started_dur>
     145        <in_progress_dur>X</in_progress_dur>
    112146    <global_preferences>
    113147        <source_project>http://a.b.c</source_project>
     
    123157       <hostid>NNN</hostid>
    124158       [ <attached_via_acct_mgr/> ]
     159           [ <suspended_via_gui/> ]
     160           [ <dont_request_more_work/> ]
     161           [ <detach_when_done/> ]
     162           [ <ended/> ]
    125163    </project>
    126164    [ ... other projects ]
     
    197235        Returns a list of the accounts associated with this meta-account. The arguments are:
    198236
    199  password_hash::
    200     the account password, hashed as MD5(password_lowercase(name)).
    201  host_cpid::
    202     Identifies the host.
    203  previous_host_cpid::
    204     The host identifier passed in the previous RPC. Host identifiers can change occasionally. This lets the account manager maintain host identity.
    205  domain_name::
     237 * '''password_hash''': the account password, hashed as MD5(password_lowercase(name)).
     238 * '''host_cpid''': Identifies the host.
     239 * '''previous_host_cpid''':
     240 The host identifier passed in the previous RPC.
     241 Host identifiers can change occasionally.
     242 This lets the account manager maintain host identity.
     243 * '''domain_name''':
    206244    The host's domain name.
    207  run mode::
     245 * '''run mode''':
    208246    The current mode (always/auto/never).
    209  gui_rpc_port, gui_rpc_password::
     247 * '''not_started_dur''':
     248    Estimated duration (elapsed time) of unstarted jobs
     249 * '''in_progress_dur''':
     250    Estimated duration (elapsed time) of jobs in progress
     251 * '''gui_rpc_port, gui_rpc_password''':
    210252    GUI RPC information. Included only if the <send_gui_rpc_info> element is included in the AM URL file (see above).
    211  global_preferences::
     253 * '''global_preferences''':
    212254    The current global preferences.
    213  venue::
     255 * '''venue''':
    214256    The host venue
    215  opaque::
     257 * '''opaque''':
    216258    Opaque data received from the AMS in the previous RPC.
    217259
     
    223265    A time interval after which another RPC should be done.
    224266 signing_key::
    225     The public key used to sign URLs, in an encoded notation. Use the BOINC crypt_prog program to generate this.
     267    The public key used to sign URLs, in an encoded notation.
     268        Use the BOINC crypt_prog program to generate this.
    226269 message::
    227270    A message to be displayed to the user.
     
    229272    New global preferences. Included only if these are newer than those in the request message.
    230273 opaque::
    231     Arbitrary XML.  Will be included in the next request message from the client.  Use this e.g. to store a host ID.
     274    Arbitrary XML.  Will be included in the next request message from the client.
     275         Use this e.g. to store a host ID.
    232276 rss_feeds::
    233     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.
     277    A list of RSS feeds to be displayed as Notices by the BOINC Manager.
     278         Typically this is a feed of news items from the account manager.
    234279
    235280For each account, the following items are returned:
     
    250295    If nonzero, detach from this project when all work is completed
    251296 resource_share::
    252     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.
    253 
    254 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.
     297    Specifies a resource share for this project.
     298        If present, this overrides the resource share reported by the project.
     299        Thus, account managers can provide per-host control of resource share.
     300
     301NOTE: the XML must be as above, with the <url> and <authenticator> elements on a single line,
     302and the <account> and </account> tags on separate lines.
    255303
    256304== Host identification ==
     
    258306BOINC uses two ID spaces for hosts:
    259307
    260     * Cross-project ID (CPID). This is used in the statistics data exported by projects. The 'authoritative' CPID is stored on the host itself. A host's CPID changes whenever it attaches to a new project. CPID is propagated to projects in scheduler RPCs. If a host is attached to several projects, its CPID (as reported by those projects) may be inconsistent for several days. Because of these properties, CPID is not useful as a primary host identifier.
    261     * Project database ID (DBID). This is a project-specific integer identifier. On a given host, it changes only in the rare case where a user copies state files from one computer to another; in that case, one of the two computers is assigned a new ID after its next scheduler RPC.
     308    * Cross-project ID (CPID).
     309      This is used in the statistics data exported by projects.
     310          The 'authoritative' CPID is stored on the host itself.
     311          A host's CPID changes whenever it attaches to a new project.
     312          CPID is propagated to projects in scheduler RPCs.
     313          If a host is attached to several projects, its CPID (as reported by those projects)
     314          may be inconsistent for several days.
     315          Because of these properties, CPID is not useful as a primary host identifier.
     316    * Project database ID (DBID).
     317          This is a project-specific integer identifier.
     318          On a given host, it changes only in the rare case
     319          where a user copies state files from one computer to another;
     320          in that case, one of the two computers is assigned a new ID after its next scheduler RPC.
    262321
    263322An account manager RPC request includes the host's CPID, and its DBID on all projects to which it's attached (see above).
     
    270329          * DBID
    271330          * CPID
    272     * On each account manager RPC, for each reported project, look up (user ID, project ID, DBID) in the host table (where 'DBID' is the one passed in the RPC request). If no record is found, create one. In any case, update the record with the CPID from the RPC request.
    273     * To show the user a list of their hosts, with current per-project credit: do a show_user.php RPC to each project to get a list of hosts. Update the corresponding records in the host table, based on the DBIDs returned by show_user.php. Delete any host table entries for this user/project that don't appear in the RPC reply. Ignore the CPIDs returned by the show_user RPC (they may not be consistent). Then do a query on the host table, grouping by CPID.
     331    * On each account manager RPC, for each reported project,
     332          look up (user ID, project ID, DBID) in the host table (where 'DBID' is the one passed in the RPC request).
     333          If no record is found, create one. In any case, update the record with the CPID from the RPC request.
     334    * To show the user a list of their hosts, with current per-project credit:
     335          do a show_user.php RPC to each project to get a list of hosts.
     336          Update the corresponding records in the host table, based on the DBIDs returned by show_user.php.
     337          Delete any host table entries for this user/project that don't appear in the RPC reply.
     338          Ignore the CPIDs returned by the show_user RPC (they may not be consistent).
     339          Then do a query on the host table, grouping by CPID.
     340