Re: [Matahari] [PATCH] schema.xml cleanup

* 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&lt;xref linkend='Resources_list_standards' /&gt;" /> +<arg name="provider" dir="I" type="sstr" desc="Provider of ocf standard, see&lt;xref linkend='Resources_list_providers' /&gt;" /> +<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=" +&lt;itemizedlist&gt; +&lt;listitem&gt; +&lt;para&gt;&lt;literal&gt;0&lt;/literal&gt;: no flag,&lt;/para&gt; +&lt;/listitem&gt; +&lt;listitem&gt; +&lt;para&gt;&lt;literal&gt;1&lt;/literal&gt;: force execution. Use this if the&lt;literal&gt;key&lt;/literal&gt; is already set.&lt;/para&gt; +&lt;/listitem&gt; +&lt;/itemizedlist&gt;" /> +<arg name="scheme" dir="I" type="sstr" desc="File format of configuration file. Currently supported are&lt;literal&gt;puppet&lt;/literal&gt; and&lt;literal&gt;augeas&lt;/literal&gt;." /> +<arg name="key" dir="I" type="sstr" desc="Key will be associated with the result of the command. The key can be used in&lt;xref linkend='Sysconfig_is_configured' /&gt;." /> +<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&lt;xref linkend='Sysconfig_run_uri' /&gt;"> +<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&lt;literal&gt;augeas&lt;/literal&gt; 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>