* 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-agent-api.txt?rev=HEAD">OCF - 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-agent-api.txt?rev=HEAD"> + 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-agent-api.txt?rev=HEAD">OCF + 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>