* Fix indentation - constistenly use 4 space for indentation
* Add some documentation for resources API (already acked)
* Adapt for change of Matahari manual generation script (using xref for linking between
methods, etc.)
Some changes require patched manual generation script, see the next patch.
---
src/host/schema.xml | 152 +++++++++---------
src/network/schema.xml | 56 +++---
src/service/schema.xml | 411 +++++++++++++++++++++++++---------------------
src/sysconfig/schema.xml | 76 +++++----
4 files changed, 373 insertions(+), 322 deletions(-)
diff --git a/src/host/schema.xml b/src/host/schema.xml
index cb179cf..1841907 100644
--- a/src/host/schema.xml
+++ b/src/host/schema.xml
@@ -1,99 +1,97 @@
<schema package="org.matahariproject">
- <eventArguments>
+ <eventArguments>
+ <arg name="timestamp" type="absTime" />
+ <arg name="sequence" type="uint32" />
+ <arg name="hostname" type="sstr"/>
+ <arg name="uuid" type="sstr"/>
+ </eventArguments>
- <arg name="timestamp" type="absTime" />
- <arg name="sequence" type="uint32" />
- <arg name="hostname" type="sstr"/>
- <arg name="uuid" type="sstr"/>
+ <class name="Host">
+ <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y" />
+ <property name="uuid" type="sstr"
access="RO" desc="Filesystem Host UUID" index="y" />
+ <property name="custom_uuid" type="sstr"
access="RO" desc="Custom Host UUID" index="y" />
- </eventArguments>
+ <property name="os" type="sstr"
access="RO" desc="The installed operating system." />
+ <property name="arch" type="sstr"
access="RO" desc="The host's architecture" />
+ <property name="wordsize" type="uint8"
access="RO" desc="The wordsize for the host"
unit="bit"/>
- <class name="Host">
- <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y" />
- <property name="uuid" type="sstr"
access="RO" desc="Filesystem Host UUID" index="y" />
- <property name="custom_uuid" type="sstr"
access="RO" desc="Custom Host UUID" index="y" />
+ <property name="memory" type="uint64"
access="RO" desc="Amount of primary memory for host"
unit="kb" />
+ <property name="swap" type="uint64"
access="RO" desc="Amount of swap for host" unit="kb" />
- <property name="os" type="sstr"
access="RO" desc="The installed operating system." />
- <property name="arch" type="sstr"
access="RO" desc="The host's architecture" />
- <property name="wordsize" type="uint8"
access="RO" desc="The wordsize for the host"
unit="bit"/>
+ <property name="cpu_count" type="uint8"
access="RO" desc="The number of logical CPUs." />
+ <property name="cpu_cores" type="uint8"
access="RO" desc="The total number of processor cores." />
+ <property name="cpu_model" type="lstr"
access="RO" desc="The processor(s) model description." />
+ <property name="cpu_flags" type="lstr"
access="RO" desc="The processor(s) CPU flags." />
- <property name="memory" type="uint64"
access="RO" desc="Amount of primary memory for host"
unit="kb" />
- <property name="swap" type="uint64"
access="RO" desc="Amount of swap for host" unit="kb" />
+ <property name="update_interval" type="uint32"
access="RW" desc="The interval at which the host sends out heartbeats and
refreshes statistics." unit="s"/>
- <property name="cpu_count" type="uint8"
access="RO" desc="The number of logical CPUs." />
- <property name="cpu_cores" type="uint8"
access="RO" desc="The total number of processor cores." />
- <property name="cpu_model" type="lstr"
access="RO" desc="The processor(s) model description." />
- <property name="cpu_flags" type="lstr"
access="RO" desc="The processor(s) CPU flags." />
+ <statistic name="last_updated" type="absTime"
desc="The last time a heartbeat occurred." />
+ <statistic name="sequence" type="uint32"
desc="The heartbeat sequence number." />
- <property name="update_interval" type="uint32"
access="RW" desc="The interval at which the host sends out heartbeats and
refreshes statistics." unit="s"/>
+ <statistic name="free_mem" type="uint64"
desc="Amount of available memory for host" unit="kb" />
+ <statistic name="free_swap" type="uint64"
desc="Amount of available swap for host" unit="kb" />
- <statistic name="last_updated" type="absTime" desc="The
last time a heartbeat occurred." />
- <statistic name="sequence" type="uint32" desc="The
heartbeat sequence number." />
+ <statistic name="load" type="map"
desc="The one/five/fifteen minute load average" />
+ <statistic name="process_statistics" type="map"
desc="Number of processes in each possible state" />
- <statistic name="free_mem" type="uint64"
desc="Amount of available memory for host" unit="kb" />
- <statistic name="free_swap" type="uint64"
desc="Amount of available swap for host" unit="kb" />
+ <method name="identify" desc="Tell the host to
beep its pc speaker." />
+ <method name="shutdown" desc="Shutdown node"
/>
+ <method name="reboot" desc="Reboot node"
/>
- <statistic name="load" type="map"
desc="The one/five/fifteen minute load average" />
- <statistic name="process_statistics" type="map"
desc="Number of processes in each possible state" />
+ <!--
+ <variablelist><title>Valid UUID lifetimes:</title>
- <method name="identify" desc="Tell the host to beep its pc
speaker." />
- <method name="shutdown" desc="Shutdown node" />
- <method name="reboot" desc="Reboot node" />
+
<varlistentry><term><literal>Filesystem</literal></term>
+ <listitem><para>
+ Automatically configured by the system during
+ installation and never reset. May be pre-populated.
+ </para></listitem>
+ </varlistentry>
- <!--
- <variablelist><title>Valid UUID lifetimes:</title>
+
<varlistentry><term><literal>Hardware</literal></term>
+ <listitem><para>
+ UUID supplied by or generated from the underlying hardware.
+ </para></listitem>
+ </varlistentry>
-
<varlistentry><term><literal>Filesystem</literal></term>
- <listitem><para>
- Automatically configured by the system during
- installation and never reset. May be pre-populated.
- </para></listitem>
- </varlistentry>
+
<varlistentry><term><literal>Reboot</literal></term>
+ <listitem><para>
+ Automatically (re)configured by the system whenever it boots.
+ </para></listitem>
+ </varlistentry>
-
<varlistentry><term><literal>Hardware</literal></term>
- <listitem><para>
- UUID supplied by or generated from the underlying hardware.
- </para></listitem>
- </varlistentry>
+
<varlistentry><term><literal>Agent</literal></term>
+ <listitem><para>
+ Automatically (re)configured by the agent whenever it starts
+ </para></listitem>
+ </varlistentry>
-
<varlistentry><term><literal>Reboot</literal></term>
- <listitem><para>
- Automatically (re)configured by the system whenever it boots.
- </para></listitem>
- </varlistentry>
+
<varlistentry><term><literal>Custom</literal></term>
+ <listitem><para>
+ Manually configured by the admin/user using the set_uuid method.
+ </para></listitem>
+ </varlistentry>
-
<varlistentry><term><literal>Agent</literal></term>
- <listitem><para>
- Automatically (re)configured by the agent whenever it starts
- </para></listitem>
- </varlistentry>
+ </variablelist>
+ -->
+ <method name="get_uuid" desc="Obtain a UUID with
the specified lifetime from the machine" >
+ <arg name="lifetime" dir="I"
type="sstr" />
+ <arg name="uuid" dir="O"
type="sstr" />
+ </method>
-
<varlistentry><term><literal>Custom</literal></term>
- <listitem><para>
- Manually configured by the admin/user using the set_uuid method.
- </para></listitem>
- </varlistentry>
+ <!--
+ <para>The only valid lifetime for <literal>set_uuid</literal>
is <literal>Custom</literal>.
+ Later implementations may support re-generating the 'Hardware' uuid.
+ </para>
+ -->
+ <method name="set_uuid" desc="Set a UUID with the
specified lifetime" >
+ <arg name="lifetime" dir="I"
type="sstr" />
+ <arg name="uuid" dir="I"
type="sstr" />
+ <arg name="rc" dir="O"
type="int32" />
+ </method>
+ </class>
- </variablelist>
- -->
- <method name="get_uuid" desc="Obtain a UUID with the specified
lifetime from the machine" >
- <arg name="lifetime" dir="I" type="sstr" />
- <arg name="uuid" dir="O" type="sstr" />
- </method>
-
- <!--
- <para>The only valid lifetime for <literal>set_uuid</literal> is
<literal>Custom</literal>.
- Later implementations may support re-generating the 'Hardware'
uuid.</para>
- -->
- <method name="set_uuid" desc="Set a UUID with the specified
lifetime" >
- <arg name="lifetime" dir="I" type="sstr" />
- <arg name="uuid" dir="I" type="sstr" />
- <arg name="rc" dir="O" type="int32" />
- </method>
-
- </class>
-
- <event name="heartbeat" args="timestamp,sequence,hostname,uuid"
/>
+ <event name="heartbeat"
args="timestamp,sequence,hostname,uuid" />
</schema>
diff --git a/src/network/schema.xml b/src/network/schema.xml
index 2458bfa..ceb1ef3 100644
--- a/src/network/schema.xml
+++ b/src/network/schema.xml
@@ -1,34 +1,34 @@
<schema package="org.matahariproject">
- <class name="Network">
- <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
- <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y" />
+ <class name="Network">
+ <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
+ <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y" />
- <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
+ <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
- <method name="list" desc="List network
interfaces">
- <arg name="iface_map" dir="O" type="list"
/>
- </method>
- <method name="start" desc="Start a network
interface">
- <arg name="iface" dir="I" type="sstr"
/>
- <arg name="status" dir="O" type="uint32"
/>
- </method>
- <method name="stop" desc="Stop a network
interface">
- <arg name="iface" dir="I" type="sstr"
/>
- <arg name="status" dir="O" type="uint32"
/>
- </method>
- <method name="status" desc="Check a network
interface">
- <arg name="iface" dir="I" type="sstr"
/>
- <arg name="status" dir="O" type="uint32"
/>
- </method>
- <method name="get_ip_address" desc="Obtain ip addressof a network
interface">
- <arg name="iface" dir="I" type="sstr"
/>
- <arg name="ip" dir="O" type="sstr"
/>
- </method>
- <method name="get_mac_address" desc="Obtain mac address of network
interface">
- <arg name="iface" dir="I" type="sstr"
/>
- <arg name="mac" dir="O" type="sstr"
/>
- </method>
- </class>
+ <method name="list" desc="List network
interfaces">
+ <arg name="iface_map" dir="O"
type="list" />
+ </method>
+ <method name="start" desc="Start a network
interface">
+ <arg name="iface" dir="I"
type="sstr" />
+ <arg name="status" dir="O"
type="uint32" />
+ </method>
+ <method name="stop" desc="Stop a network
interface">
+ <arg name="iface" dir="I"
type="sstr" />
+ <arg name="status" dir="O"
type="uint32" />
+ </method>
+ <method name="status" desc="Check a network
interface">
+ <arg name="iface" dir="I"
type="sstr" />
+ <arg name="status" dir="O"
type="uint32" />
+ </method>
+ <method name="get_ip_address" desc="Obtain ip addressof a
network interface">
+ <arg name="iface" dir="I"
type="sstr" />
+ <arg name="ip" dir="O"
type="sstr" />
+ </method>
+ <method name="get_mac_address" desc="Obtain mac address of
network interface">
+ <arg name="iface" dir="I"
type="sstr" />
+ <arg name="mac" dir="O"
type="sstr" />
+ </method>
+ </class>
</schema>
diff --git a/src/service/schema.xml b/src/service/schema.xml
index 0790eb8..7c6cdb2 100644
--- a/src/service/schema.xml
+++ b/src/service/schema.xml
@@ -1,206 +1,245 @@
<schema package="org.matahariproject">
- <eventArguments>
+ <eventArguments>
+ <arg name="timestamp" type="absTime" />
+ <arg name="sequence" type="uint32" />
- <arg name="timestamp" type="absTime" />
- <arg name="sequence" type="uint32" />
+ <arg name="name" type="sstr" />
+ <arg name="standard" type="sstr" />
+ <arg name="provider" type="sstr" />
+ <arg name="agent" type="sstr" />
- <arg name="name" type="sstr" />
- <arg name="standard" type="sstr" />
- <arg name="provider" type="sstr" />
- <arg name="agent" type="sstr" />
+ <arg name="action" type="sstr" />
+ <arg name="interval" type="uint32" />
+ <arg name="rc" type="uint32" />
- <arg name="action" type="sstr" />
- <arg name="interval" type="uint32" />
- <arg name="rc" type="uint32" />
+ <arg name="expected-rc" type="uint32" />
+ <arg name="userdata" type="sstr" />
+ </eventArguments>
- <arg name="expected-rc" type="uint32" />
- <arg name="userdata" type="sstr" />
+ <event name="resource_op"
args="timestamp,sequence,name,standard,provider,agent,action,interval,rc,expected-rc,userdata"
/>
- </eventArguments>
+ <!--
+ <para>
+ Simple API for accessing system services
+ </para>
- <event
name="resource_op" args="timestamp,sequence,name,standard,provider,agent,action,interval,rc,expected-rc,userdata"
/>
+ <para>
+ For more advanced functionality, use the Resources API with
standard="lsb"
+ </para>
+ -->
- <!--
- Services API
- Simple API for accessing system services
-
- For more advanced functionality, use the Resources API with
standard="lsb"
- -->
+ <class name="Services">
+ <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
+ <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y"/>
- <class name="Services">
- <property name="uuid" type="sstr" access="RO"
desc="Host UUID" />
- <property name="hostname" type="sstr" access="RO"
desc="Hostname" index="y"/>
+ <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
- <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
+ <method name="list" desc="List known system
services">
+ <arg name="agents" dir="O"
type="list" />
+ </method>
+ <method name="enable" desc="Configure a system service
to start at boot">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="rc" dir="O"
type="uint32" />
+ </method>
+ <method name="disable" desc="Configure a system service
_not_ to start at boot">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="rc" dir="O"
type="uint32" />
+ </method>
+ <method name="start" desc="Start a system
service">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="timeout" dir="I"
type="uint32" />
+ <arg name="rc" dir="O"
type="uint32" />
+ </method>
+ <method name="stop" desc="Stop a system
service">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="timeout" dir="I"
type="uint32" />
+ <arg name="rc" dir="O"
type="uint32" />
+ </method>
+ <method name="status" desc="Check the health of a
system service">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="timeout" dir="I"
type="uint32" />
+ <arg name="rc" dir="O"
type="uint32" />
+ </method>
+ <method name="describe" desc="Obtain XML description of a
system service">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="xml" dir="O"
type="sstr" />
+ </method>
+ </class>
- <method name="list" desc="List known system
services">
- <arg name="agents" dir="O" type="list"
/>
- </method>
- <method name="enable" desc="Configure a system service to
start at boot">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- </method>
- <method name="disable" desc="Configure a system service _not_
to start at boot">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- </method>
- <method name="start" desc="Start a system service">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="timeout" dir="I" type="uint32"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- </method>
- <method name="stop" desc="Stop a system service">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="timeout" dir="I" type="uint32"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- </method>
- <method name="status" desc="Check the health of a system
service">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="timeout" dir="I" type="uint32"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- </method>
- <method name="describe" desc="Obtain XML description of a
system service">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="xml" dir="O" type="sstr"
/>
- </method>
- </class>
+ <!--
+ <para>
+ Fully featured API for controlling and monitoring services
+ conforming to a standardized specification.
+ </para>
+ <para>
+ Currently supported standards:
+ <literal>windows</literal>,
+ <literal>lsb</literal> (Linux Standard Base),
+ <literal>ocf</literal> (Open Cluster Framework),
+ <literal>systemd</literal>.
+ </para>
+ <para>
+ On Windows, <literal>lsb</literal> is an alias for
<literal>windows</literal>.
+ </para>
+ -->
- <!--
- Resources API
+ <class name="Resources">
+ <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
+ <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y"/>
- Fully featured API for controlling and monitoring services
- conforming to a standardized specification.
-
- Currently supported standards: windows, lsb (Linux Standard Base), ocf (Open
Cluster Framework)
- On Windows, 'lsb' is an alias for 'windows'
- -->
+ <method name="list_standards" desc="List known resource
standards (OCF, LSB, systemd, etc)">
+ <arg name="standards" dir="O"
type="list" />
+ </method>
- <class name="Resources">
- <property name="uuid" type="sstr" access="RO"
desc="Host UUID" />
- <property name="hostname" type="sstr" access="RO"
desc="Hostname" index="y"/>
+ <method name="list_providers" desc="List known providers (if
supported) for a given standard">
+ <arg name="standard" dir="I"
type="sstr" />
+ <arg name="providers" dir="O"
type="list" />
+ </method>
- <method name="list_standards" desc="List known resource standards
(OCF, LSB, Upstart, etc)">
- <arg name="standards" dir="O" type="list"
/>
- </method>
- <method name="list_providers" desc="List known providers (if
supported) for a given standard">
- <arg name="standard" dir="I" type="sstr"
/>
- <arg name="providers" dir="O" type="list"
/>
- </method>
- <method name="list" desc="List known resource types for a
given standard and provider">
- <arg name="standard" dir="I" type="sstr"
/>
- <arg name="provider" dir="I" type="sstr"
/>
- <arg name="agents" dir="O" type="list"
/>
- </method>
+ <method name="list" desc="List known resource types
for a given standard and provider">
+ <arg name="standard" dir="I"
type="sstr" />
+ <arg name="provider" dir="I"
type="sstr" />
+ <arg name="agents" dir="O"
type="list" />
+ </method>
- <method name="describe" desc="Obtain XML description of a
resource">
- <arg name="standard" dir="I" type="sstr"
/>
- <arg name="provider" dir="I" type="sstr"
/>
- <arg name="agent" dir="I" type="sstr"
/>
- <arg name="xml" dir="O" type="sstr"
/>
- </method>
- <!--
- <para>The <literal>rc</literal> output parameter warrants some
additional discussion.
- The potential return values depends on which <literal>standard</literal>
is being
- used. In the case of <literal>OCF</literal>, these values are defined by
the
- <ulink
url="http://www.opencf.org/cgi-bin/viewcvs.cgi/specs/ra/resource-age...
- resource agent specification</ulink>. However, see <xref
linkend="ocf_return_vals"/>
- for an overview of the OCF resource agent return codes.</para>
+ <method name="describe" desc="Obtain XML description of a
resource">
+ <arg name="standard" dir="I"
type="sstr" />
+ <arg name="provider" dir="I"
type="sstr" />
+ <arg name="agent" dir="I"
type="sstr" />
+ <arg name="xml" dir="O"
type="sstr" />
+ </method>
- <table id="ocf_return_vals">
- <title>OCF Resource Agent Exit Codes</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Value(s)</entry>
- <entry>OCF Name</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry><literal>0</literal></entry>
- <entry><literal>OCF_SUCCESS</literal></entry>
- <entry>Success. The command complete successfully. This is the expected
result for all start, stop, promote and demote commands.</entry>
- </row>
- <row>
- <entry><literal>1</literal></entry>
- <entry><literal>OCF_ERR_GENERIC</literal></entry>
- <entry>Generic "there was a problem" error code.</entry>
- </row>
- <row>
- <entry><literal>2</literal></entry>
- <entry><literal>OCF_ERR_ARGS</literal></entry>
- <entry>The resource's configuration is not valid on this machine. Eg.
Refers to a location/tool not found on the node.</entry>
- </row>
- <row>
- <entry><literal>3</literal></entry>
- <entry><literal>OCF_ERR_UNIMPLEMENTED</literal></entry>
- <entry>The requested action is not implemented.</entry>
- </row>
- <row>
- <entry><literal>4</literal></entry>
- <entry><literal>OCF_ERR_PERM</literal></entry>
- <entry>The resource agent does not have sufficient privileges to complete
the task.</entry>
- </row>
- <row>
- <entry><literal>5</literal></entry>
- <entry><literal>OCF_ERR_INSTALLED</literal></entry>
- <entry>The tools required by the resource are not installed on this
machine.</entry>
- </row>
- <row>
- <entry><literal>6</literal></entry>
- <entry><literal>OCF_ERR_CONFIGURED</literal></entry>
- <entry>The resource's configuration is invalid. Eg. A required
parameters are missing.</entry>
- </row>
- <row>
- <entry><literal>7</literal></entry>
- <entry><literal>OCF_NOT_RUNNING</literal></entry>
- <entry>The resource is safely stopped.</entry>
- </row>
- <row>
- <entry><literal>8</literal></entry>
- <entry><literal>OCF_RUNNING_MASTER</literal></entry>
- <entry>The resource is running in Master mode.</entry>
- </row>
- <row>
- <entry><literal>9</literal></entry>
- <entry><literal>OCF_FAILED_MASTER</literal></entry>
- <entry>The resource is in Master mode but has failed. The resource will be
demoted, stopped and then started (and possibly promoted) again.</entry>
- </row>
- <row>
- <entry>other</entry>
- <entry>N/A</entry>
- <entry>Custom error code.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- -->
- <method name="invoke" desc="Perform a custom action on a
resource">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="standard" dir="I" type="sstr"
/>
- <arg name="provider" dir="I" type="sstr"
/>
- <arg name="agent" dir="I" type="sstr"
/>
- <arg name="action" dir="I" type="sstr"
/>
- <arg name="interval" dir="I" type="uint32"
/>
- <arg name="parameters" dir="I" type="map"
/>
- <arg name="timeout" dir="I" type="uint32"
/>
- <arg name="expected-rc" dir="I" type="uint32"
/>
- <arg name="rc" dir="O" type="uint32"
/>
- <arg name="sequence" dir="O" type="uint32"
/>
- <arg name="userdata" dir="IO" type="sstr"
/>
- </method>
- <method name="cancel" desc="Cancel a pending or running
action on a resource">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="action" dir="I" type="sstr"
/>
- <arg name="interval" dir="I" type="uint32"
/>
- <arg name="timeout" dir="I" type="uint32"
/>
- </method>
- <method name="fail" desc="Indicate a resource has
failed">
- <arg name="name" dir="I" type="sstr"
/>
- <arg name="rc" dir="I" type="uint32"
/>
- </method>
- </class>
+ <!--
+ <para>
+ <literal>action</literal> depends on the standard/provider/agent
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>OCF</literal>: see
+ <ulink
url="http://www.opencf.org/cgi-bin/viewcvs.cgi/specs/ra/resource-age...
+ ocf specification
+ </ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>LSB</literal>:
enable/disable/start/stop/status
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>systemd</literal>: see
+ <ulink
url="http://www.linuxcertif.com/man/1/systemctl/">
+ man systemctl
+ </ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The <literal>rc</literal> output parameter warrants some
additional discussion.
+ The potential return values depends on which
<literal>standard</literal> is being
+ used. In the case of <literal>OCF</literal>, these values are
defined by the
+ <ulink
url="http://www.opencf.org/cgi-bin/viewcvs.cgi/specs/ra/resource-age...
+ resource agent specification</ulink>. However, see <xref
linkend="ocf_return_vals"/>
+ for an overview of the OCF resource agent return codes.
+ </para>
+
+ <table id="ocf_return_vals">
+ <title>OCF Resource Agent Exit Codes</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Value(s)</entry>
+ <entry>OCF Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>0</literal></entry>
+ <entry><literal>OCF_SUCCESS</literal></entry>
+ <entry>Success. The command complete successfully. This is the
expected result for all start, stop, promote and demote commands.</entry>
+ </row>
+ <row>
+ <entry><literal>1</literal></entry>
+
<entry><literal>OCF_ERR_GENERIC</literal></entry>
+ <entry>Generic "there was a problem" error
code.</entry>
+ </row>
+ <row>
+ <entry><literal>2</literal></entry>
+ <entry><literal>OCF_ERR_ARGS</literal></entry>
+ <entry>The resource's configuration is not valid on this
machine. Eg. Refers to a location/tool not found on the node.</entry>
+ </row>
+ <row>
+ <entry><literal>3</literal></entry>
+
<entry><literal>OCF_ERR_UNIMPLEMENTED</literal></entry>
+ <entry>The requested action is not implemented.</entry>
+ </row>
+ <row>
+ <entry><literal>4</literal></entry>
+ <entry><literal>OCF_ERR_PERM</literal></entry>
+ <entry>The resource agent does not have sufficient privileges to
complete the task.</entry>
+ </row>
+ <row>
+ <entry><literal>5</literal></entry>
+
<entry><literal>OCF_ERR_INSTALLED</literal></entry>
+ <entry>The tools required by the resource are not installed on this
machine.</entry>
+ </row>
+ <row>
+ <entry><literal>6</literal></entry>
+
<entry><literal>OCF_ERR_CONFIGURED</literal></entry>
+ <entry>The resource's configuration is invalid. Eg. A required
parameters are missing.</entry>
+ </row>
+ <row>
+ <entry><literal>7</literal></entry>
+
<entry><literal>OCF_NOT_RUNNING</literal></entry>
+ <entry>The resource is safely stopped.</entry>
+ </row>
+ <row>
+ <entry><literal>8</literal></entry>
+
<entry><literal>OCF_RUNNING_MASTER</literal></entry>
+ <entry>The resource is running in Master mode.</entry>
+ </row>
+ <row>
+ <entry><literal>9</literal></entry>
+
<entry><literal>OCF_FAILED_MASTER</literal></entry>
+ <entry>The resource is in Master mode but has failed. The resource
will be demoted, stopped and then started (and possibly promoted) again.</entry>
+ </row>
+ <row>
+ <entry>other</entry>
+ <entry>N/A</entry>
+ <entry>Custom error code.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ -->
+ <method name="invoke" desc="Perform a custom action on
a resource">
+ <arg name="name" dir="I"
type="sstr" desc="Identification of the action" />
+ <arg name="standard" dir="I"
type="sstr" desc="Resource standard to be used, see <xref
linkend='Resources_list_standards' />" />
+ <arg name="provider" dir="I"
type="sstr" desc="Provider of ocf standard, see <xref
linkend='Resources_list_providers' />" />
+ <arg name="agent" dir="I"
type="sstr" desc="Name of the resource affected by action" />
+ <arg name="action" dir="I"
type="sstr" desc="Action that will be executed on resource" />
+ <arg name="interval" dir="I"
type="uint32" desc="Event resource_op will be risen each interval
miliseconds (not supported by dbus agent)" />
+ <arg name="parameters" dir="I"
type="map" desc="Additional parameters for the action (enviromental
variables for OCF)" />
+ <arg name="timeout" dir="I"
type="uint32" desc="Timeout for the action in miliseconds" />
+ <arg name="expected-rc" dir="I"
type="uint32" />
+ <arg name="rc" dir="O"
type="uint32" desc="Return code of the action" />
+ <arg name="sequence" dir="O"
type="uint32" />
+ <arg name="userdata" dir="IO"
type="sstr" />
+ </method>
+ <method name="cancel" desc="Cancel a pending or running
action on a resource. name, action and interval must be the same as for invoke
method">
+ <arg name="name" dir="I"
type="sstr" desc="Identification of the action" />
+ <arg name="action" dir="I"
type="sstr" desc="Action that is running or pending" />
+ <arg name="interval" dir="I"
type="uint32" desc="Interval in miliseconds" />
+ <arg name="timeout" dir="I"
type="uint32" desc="Timeout for cancelling in miliseconds" />
+ </method>
+ <method name="fail" desc="Indicate a resource has
failed">
+ <arg name="name" dir="I"
type="sstr" />
+ <arg name="rc" dir="I"
type="uint32" />
+ </method>
+ </class>
</schema>
diff --git a/src/sysconfig/schema.xml b/src/sysconfig/schema.xml
index bc41a55..0635a09 100644
--- a/src/sysconfig/schema.xml
+++ b/src/sysconfig/schema.xml
@@ -1,48 +1,62 @@
<schema package="org.matahariproject">
- <!-- Config API -->
+ <!--
+ <para>
+ API for system configuration.
+ </para>
+ -->
<class name="Sysconfig">
- <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
- <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y"/>
+ <property name="uuid" type="sstr"
access="RO" desc="Host UUID" />
+ <property name="hostname" type="sstr"
access="RO" desc="Hostname" index="y"/>
<!--
- <para>It is useful to have some information in a property since you can
- filter on properties. This property is intended to be used as a
- flag to know whether or not initial configuration of a host has
- been done or not. It is not automatically set. Once the
- configuring entity has completed its tasks, it should set this
- property itself.</para>
+ <para>
+ It is useful to have some information in a property since you can
+ filter on properties. This property is intended to be used as a
+ flag to know whether or not initial configuration of a host has
+ been done or not. It is not automatically set. Once the
+ configuring entity has completed its tasks, it should set this
+ property itself.
+ </para>
-->
- <property name="is_postboot_configured" type="uint32"
access="RW" desc="Set if agent is configured." />
+ <property name="is_postboot_configured" type="uint32"
access="RW" desc="Set if agent is configured." />
- <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
+ <statistic name="qmf-gen-no-crash" type="absTime"
desc="Dummy stat to stop qmf-gen from crashing." />
- <method name="run_uri" desc="Send configure uri
method">
- <arg name="uri" dir="I"
type="sstr" />
- <arg name="flags" dir="I"
type="uint32" />
- <arg name="scheme" dir="I"
type="sstr" />
- <arg name="key" dir="I"
type="sstr" />
- <arg name="status" dir="O"
type="sstr" />
+ <method name="run_uri" desc="Configure system using
configuration file on given uri">
+ <arg name="uri" dir="I"
type="sstr" desc="URI with configuration file. Same protocols as cURL
are supported." />
+ <arg name="flags" dir="I"
type="uint32" desc="
+ <itemizedlist>
+ <listitem>
+ <para><literal>0</literal>:
no flag,</para>
+ </listitem>
+ <listitem>
+ <para><literal>1</literal>:
force execution. Use this if the <literal>key</literal> is
already set.</para>
+ </listitem>
+ </itemizedlist>" />
+ <arg name="scheme" dir="I"
type="sstr" desc="File format of configuration file. Currently supported
are <literal>puppet</literal> and
<literal>augeas</literal>." />
+ <arg name="key" dir="I"
type="sstr" desc="Key will be associated with the result of the command.
The key can be used in <xref linkend='Sysconfig_is_configured'
/>." />
+ <arg name="status" dir="O"
type="sstr" desc="Result of the command." />
</method>
- <method name="run_string" desc="Send configure text
method">
- <arg name="text" dir="I"
type="sstr" />
- <arg name="flags" dir="I"
type="uint32" />
- <arg name="scheme" dir="I"
type="sstr" />
- <arg name="key" dir="I"
type="sstr" />
- <arg name="status" dir="O"
type="sstr" />
+ <method name="run_string" desc="Configure system using
given configuration text. Most arguments are the same as <xref
linkend='Sysconfig_run_uri' />">
+ <arg name="text" dir="I"
type="sstr" desc="Configuration string" />
+ <arg name="flags" dir="I"
type="uint32" desc="" />
+ <arg name="scheme" dir="I"
type="sstr" desc="" />
+ <arg name="key" dir="I"
type="sstr" desc="" />
+ <arg name="status" dir="O"
type="sstr" desc="" />
</method>
- <method name="query" desc="Perform query
lookup">
- <arg name="text" dir="I"
type="sstr" />
- <arg name="flags" dir="I"
type="uint32" />
- <arg name="scheme" dir="I"
type="sstr" />
- <arg name="data" dir="O"
type="sstr" />
+ <method name="query" desc="Perform query
lookup">
+ <arg name="text" dir="I"
type="sstr" desc="Text of the query." />
+ <arg name="flags" dir="I"
type="uint32" desc="Not used now." />
+ <arg name="scheme" dir="I"
type="sstr" desc="Only
<literal>augeas</literal> is supported." />
+ <arg name="data" dir="O"
type="sstr" desc="Result of the query." />
</method>
- <method name="is_configured" desc="Check if system is
configured">
- <arg name="key" dir="I"
type="sstr" />
- <arg name="status" dir="O"
type="sstr" />
+ <method name="is_configured" desc="Check if system is
configured">
+ <arg name="key" dir="I"
type="sstr" desc="Configuration key" />
+ <arg name="status" dir="O"
type="sstr" desc="Result of command associated with the key" />
</method>
</class>
</schema>
--
1.7.7