mirror of https://github.com/BOINC/boinc.git
268 lines
8.5 KiB
XML
268 lines
8.5 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|
<sect1 id="configuration">
|
|
<title>Configuration</title>
|
|
|
|
<para>
|
|
The DC-API library uses a configuration file to control its operations. The
|
|
location of the config file must be specified by the master application when
|
|
it calls the <function><link
|
|
linkend="DC-initMaster">DC_initMaster()</link></function> function.
|
|
<note>
|
|
<para>
|
|
Individual work units may also use a config file that has a slightly
|
|
different format than the master's config file. Work unit config files
|
|
however are usually generated by the DC-API library on the master side so
|
|
applications should not be concerned about it.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
|
|
<sect2>
|
|
<title>Configuration file format</title>
|
|
|
|
<para>
|
|
The DC-API configuration file contains key-value pairs organized into
|
|
groups. The full syntax description can be found in the
|
|
<ulink
|
|
url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
|
|
Entry Specification</ulink>, but we
|
|
also give a brief explanation below.
|
|
</para>
|
|
<para>
|
|
Lines starting with <literal>#</literal> are considered comments
|
|
and are ignored. Groups are started by a line containing the group's name
|
|
between brackets (<literal>[</literal> and <literal>]</literal>). Groups
|
|
are terminated by the start of an other group or by the end of the file.
|
|
</para>
|
|
<para>
|
|
A group may contain a list of <literal>key = value</literal> assignments,
|
|
each in a separate line. White space arount the <literal>=</literal>
|
|
character is ignored. Note that the DC-API do not use the localized string
|
|
feature of the Desktop Entry Specification.
|
|
</para>
|
|
<para>
|
|
Configuration values can be of 4 types:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Simple strings. According to the format specification, they must be
|
|
UTF-8 encoded.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Integer values.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Floating point values. For both integer and floating point values,
|
|
the following suffixes are recognized:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>kb, kib</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 2<superscript>10</superscript> (1024)
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>mb, mib</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 2<superscript>20</superscript>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>gb, gib</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 2<superscript>30</superscript>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>min</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 60
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>h, hour</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 3600
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>day</term>
|
|
<listitem>
|
|
<para>
|
|
A multiplier of 86400
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Boolean values. The strings <literal>true</literal>,
|
|
<literal>yes</literal> and <literal>on</literal> means true, the
|
|
strings <literal>false</literal>, <literal>no</literal> and
|
|
<literal>off</literal> are considered false.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Generic configuration items</title>
|
|
|
|
<para>
|
|
The DC-API configuration file should contain a group called
|
|
<literal>[Master]</literal> that defines global configuration options.
|
|
There may be also groups called <literal>[Client-CLIENTNAME]</literal> where
|
|
<literal>CLIENTNAME</literal> is the logical name of a client application
|
|
the master wishes to start (the same string that is passed to the
|
|
<function><link linkend="DC-createWU">DC_createWU()</link></function> function).
|
|
</para>
|
|
<para>
|
|
Default values for client-specific configuration options may also be
|
|
specified in the <literal>[Master]</literal> group. If the same key is
|
|
also present in a client-specific group, the client-specific value will
|
|
override the value in the <literal>[Master]</literal> group.
|
|
</para>
|
|
|
|
<sect3>
|
|
<title>Configuration values for the master application</title>
|
|
|
|
<para>
|
|
The following entries can be specified in the <literal>[Master]</literal>
|
|
group. Grid backends may require and/or allow further items; refer to the
|
|
backend-specific documentation.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>WorkingDirectory</term>
|
|
<listitem>
|
|
<para>
|
|
REQUIRED. The working directory of the master application. The value
|
|
must be an absolute path. The DC-API sets the master's current
|
|
directory to the value specified here when the <function><link
|
|
linkend="DC-initMaster">DC_initMaster()</link></function>
|
|
function is called.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LogLevel</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies the verbosity of log messages generated by the
|
|
DC-API or by the master application if it uses the <function><link
|
|
linkend="DC-log">DC_log()</link></function> or <function><link
|
|
linkend="DC-vlog">DC_vlog()</link></function> functions. The allowed values
|
|
in the order of increasing priority are <literal>Debug</literal>,
|
|
<literal>Info</literal>, <literal>Notice</literal>,
|
|
<literal>Warning</literal>, <literal>Error</literal> and
|
|
<literal>Critical</literal>, the default being
|
|
<literal>Notice</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LogFile</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies the name of the file where log messages should
|
|
be written to. If not specified, log messages are sent to the
|
|
application's standard output.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Configuration values individual work units</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>LogLevel</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies the verbosity of log messages generated by the
|
|
DC-API or by the client application if it uses the <function><link
|
|
linkend="DC-log">DC_log()</link></function> or <function><link
|
|
linkend="DC-vlog">DC_vlog()</link></function> functions. The
|
|
allowed values in the order of increasing priority are
|
|
<literal>Debug</literal>, <literal>Info</literal>,
|
|
<literal>Notice</literal>, <literal>Warning</literal>,
|
|
<literal>Error</literal> and <literal>Critical</literal>, the
|
|
default being <literal>Notice</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>LogFile</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies the name of the file where log messages should
|
|
be written to. The value must be a relative file name without any
|
|
path components.
|
|
</para>
|
|
<para>
|
|
The default value is determined by the DC-API when it creates the
|
|
work unit and generally it should not be overridden.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>SendCfgKeys</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies a <literal>;</literal>-separated list of
|
|
configuration keys that should be sent to the client application
|
|
when a work unit is created. <literal>LogLevel</literal> and
|
|
<literal>LogFile</literal> are always included so those should not
|
|
be listed.
|
|
</para>
|
|
<para>
|
|
The client application may use the <function><link
|
|
linkend="DC-getCfgStr">DC_getCfgStr()</link></function>,
|
|
<function><link
|
|
linkend="DC-getCfgInt">DC_getCfgInt()</link></function>, and
|
|
<function><link
|
|
linkend="DC-getCfgBool">DC_getCfgBool()</link></function>
|
|
functions to access the values of the keys specified by
|
|
<literal>SendCfgKeys</literal>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>DefaultPriority</term>
|
|
<listitem>
|
|
<para>
|
|
OPTIONAL. Specifies the default priority of the work unit. The
|
|
priority is an integer number; its allowed range and exact meaning
|
|
depends on the grid backend. The default value is 0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
<!-- vim: set ai sw=2 tw=80: -->
|