boinc/doc/protocol.html

<h2>The BOINC client/server protocol</h2>

<h3>Protocol nucleus</h3>
<p>
The core client communicates with scheduling servers using HTTP.
The following "nucleus" of the protocol should be considered immutable.
This will allow any version of the core client to talk to
any version of the scheduling server,
and for the server, if needed,
to tell the core client that it's out of date.
The form of the request is:
<pre>
&lt;scheduler_request>
    &lt;platform>intel-linux&lt;/platform>
    &lt;version_num>1&lt;/version_num>
    ... other elements
&lt;/scheduler_request>
</pre>
The "platform" and "version_num" elements identify the
version of the core client originating the request.

<p>
The form of the reply is:

<pre>
&lt;scheduler_reply>
    [ &lt;message priority="low"> arbitrary text &lt;/message> ... ]
    [ &lt;request_delay>3600&lt;/request_delay> ]
    [ &lt;redirect>URL&lt;/redirect> ]
    ... other elements
&lt;/scheduler_reply>
</pre>

<p
Each <b>message</b> element is a message to the participant.
<ul>
<li>
If the priority is "high", the core client should try
to ensure that the participant sees the message;
for example, by displaying it in a popup window.
It should not, however, wait for user input, as this
could starve other projects.
This should be reserved for situations where definitive action
is required, e.g. the user must download a new version of the
core client in order to continue participating in this project.
<li>
If the priority is "low" (default) the core client should
allow the participant to see the message, but should not require it.
For example, it could the message to a log file.
</ul>
<p>
A reply message can contain multiple message elements.

<p>
A <b>request_delay</b> element instructs the client
to not issue another request until the indicated number
of seconds has elapsed.
<p>
A <b>redirect</b> element gives the URL for a scheduling
server for this project.
If present, the core client should replace its list
of scheduling servers for this project.
The reply may contain multiple <b>redirect</b> elements.


<h3>Extensible protocol</h3>
<p>
The remaining protocol may evolve over time.
Request elements include

<pre>
&lt;prefs_mod_time>0&lt;/prefs_mod_time>
&lt;authenticator>3f7b90793a0175ad0bda68684e8bd136&lt;/authenticator>
&lt;hostid>1&lt;/hostid>
&lt;work_req_seconds>1000&lt;/work_req_seconds>
&lt;host_info>
    &lt;timezone>28800&lt;/timezone>
    &lt;domain_name>localhost.localdomain&lt;/domain_name>
    &lt;ip_addr>127.0.0.1&lt;/ip_addr>
    &lt;conn_frac>0.000000&lt;/conn_frac>
    &lt;on_frac>0.000000&lt;/on_frac>
    &lt;p_ncpus>1&lt;/p_ncpus>
    &lt;p_vendor>GenuineIntel&lt;/p_vendor>
    &lt;p_model>Pentium&lt;/p_model>
    &lt;p_fpops>0.000000&lt;/p_fpops>
    &lt;p_iops>0.000000&lt;/p_iops>
    &lt;p_membw>0.000000&lt;/p_membw>
    &lt;p_calculated>0.000000&lt;/p_calculated>
    &lt;os_name>Linux&lt;/os_name>
    &lt;os_version>2.2.14-5.0&lt;/os_version>
    &lt;m_nbytes>197427200.000000&lt;/m_nbytes>
    &lt;m_cache>131072.000000&lt;/m_cache>
    &lt;m_swap>178012160.000000&lt;/m_swap>
    &lt;d_total>22108344320.000000&lt;/d_total>
    &lt;d_free>18332545024.000000&lt;/d_free>
    &lt;n_bwup>0.000000&lt;/n_bwup>
    &lt;n_bwdown>0.000000&lt;/n_bwdown>
&lt;/host_info>
&lt;result>
    &lt;name>uc_wu_0&lt;/name>
    &lt;exit_status>0&lt;/exit_status>
    &lt;cpu_time>0.020000&lt;/cpu_time>
    &lt;output_file>
        &lt;md5_cksum>3f7b90793a0175ad0bda68684e8bd136&lt;/md5_cksum>
        &lt;file_name>uc_wu_0_0&lt;/file_name>
    &lt;/output_file>
&lt;/result>
</pre>

<p>
Reply elements include
<pre>
&lt;request_delay>10&lt;/request_delay>
&lt;message priority="low">no work available&lt;/message>
&lt;prefs_mod_time>123123&lt;/prefs_mod_time>
&lt;preferences>
    &lt;low_water_days>1.2&lt;/low_water_days>
    &lt;high_water_days>2.5&lt;/high_water_days>
    &lt;disk_max_used_gb>0.4&lt;/disk_max_used_gb>
    &lt;disk_max_used_pct>50&lt;/disk_max_used_pct>
    &lt;disk_min_free_gb>0.4&lt;/disk_min_free_gb>
    &lt;project>
        &lt;master_url>http://localhost.localdomain&lt;/master_url>
        &lt;email_addr>david@localdomain&lt;/email_addr>
        &lt;authenticator>123892398&lt;/authenticator>
        &lt;resource_share>10&lt;/resource_share>
        &lt;project_specific>
            &lt;color-scheme>Tahiti Sunset&lt;/color-scheme>
        &lt;/project_specific>
    &lt;/project>
&lt;/preferences>
&lt;result_ack>
    &lt;name>uc_wu_0&lt;/name>
&lt;/result_ack>
</pre>