diff --git a/api/classes/iohyve.rst b/api/classes/iohyve.rst index 57e973d..a9f2711 100644 --- a/api/classes/iohyve.rst +++ b/api/classes/iohyve.rst @@ -148,7 +148,30 @@ The "fetchiso" action is used to retrieve the installation ISO. It is used with "name": "response", "namespace": "sysadm" } - + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"iohyve", + "state" : "running" OR "finished", + "filename", + "percent_done", + "download_rate", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: listisos, iohyve .. _List ISOs: diff --git a/api/classes/pkg.rst b/api/classes/pkg.rst index e87e7ad..65f1776 100644 --- a/api/classes/pkg.rst +++ b/api/classes/pkg.rst @@ -225,7 +225,29 @@ The "pkg_info" action reads the pkg database directly and returns any relevant i "name": "response", "namespace": "sysadm" } - + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_info", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_search, pkg .. _Search Packages: @@ -404,6 +426,28 @@ The "pkg_search" action searches the package database for pkgs which match the g "namespace": "sysadm" } +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_search", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: list_categories, pkg .. _List Categories: @@ -502,6 +546,29 @@ The "list_categories" action lists all the known, non-empty categories within th "name": "response", "namespace": "sysadm" } + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "list_categories", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: list_repos, pkg .. _List Repositories: @@ -549,7 +616,29 @@ action are valid as the optional "repo" argument for the other pkg API actions. "name": "response", "namespace": "sysadm" } - + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "list_repos", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_audit, pkg .. _Audit Packages: @@ -600,7 +689,31 @@ The "pkg_audit" action performs an audit of all installed packages and reports a "name": "response", "namespace": "sysadm" } - + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_audit", + "vulnerable_pkgs" : ["pkg 1"], ["pkg 2"], + "impacts_pkgs" : ["pkg 1", "pkg 2"], + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_upgrade, pkg .. _Upgrade Packages: @@ -649,7 +762,29 @@ instructions on how to subscribe to and query dispatcher events. "name": "response", "namespace": "sysadm" } - + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_upgrade", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_check_upgrade, pkg .. _Check Packages: @@ -699,6 +834,29 @@ instructions on how to subscribe to and query dispatcher events. "namespace": "sysadm" } +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_check_upgrade" + "updates_available" : "true" OR "false", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_update, pkg .. _Update Package Database: @@ -752,6 +910,28 @@ If you include "force" = "true", it forces :command:`pkg` to completely resync a "namespace": "sysadm" } +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_update", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_lock, pkg_unlock, pkg .. _Lock/Unlock Packages: @@ -811,6 +991,28 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di "namespace": "sysadm" } +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_lock", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + **REST Request** .. code-block:: json @@ -852,6 +1054,28 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di "namespace": "sysadm" } +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_unlock", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + .. index:: pkg_install, pkg .. _Install Packages: @@ -905,6 +1129,28 @@ Unless the "repo" is specified, :command:`pkg` will automatically determine the "name": "response", "namespace": "sysadm" } + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_install", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } .. index:: pkg_remove, pkg @@ -961,4 +1207,26 @@ The uninstall messages will be returned as a dispatcher event. Refer to the :ref "id": "fooid", "name": "response", "namespace": "sysadm" - } \ No newline at end of file + } + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"pkg", + "state" : "running" OR "finished", + "pkg_log", + "action" : "pkg_remove", + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } \ No newline at end of file diff --git a/api/classes/updates.rst b/api/classes/updates.rst index 89f01be..9b7eedf 100644 --- a/api/classes/updates.rst +++ b/api/classes/updates.rst @@ -217,4 +217,25 @@ The "startupdate" action starts the specified update. You must specify a "target "id": "fooid", "name": "response", "namespace": "sysadm" + } + +**Dispatcher Events System Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : "sysadm"/"update", + "state" : "running" OR "finished", + "update_log" + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } } \ No newline at end of file diff --git a/api/events.rst b/api/events.rst new file mode 100644 index 0000000..22cde3e --- /dev/null +++ b/api/events.rst @@ -0,0 +1,231 @@ +.. _Events: + +Events +====== + +The "events" namespace can be used to setup and receive asynchronous updates about system status and other types of system notifications. + +.. note:: + the events namespace does not really translate over to REST which was not designed for asynchronous events. For this reason, only Websocket examples are used in this section. + +Every events request contains the following parameters: + ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++=================================+===============+======================================================================================================================+ +| id | | any unique value for the request; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| name | | supported values are "subscribe" or unsubscribe" | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| namespace | events | | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ +| args | | values vary by type of class | +| | | | ++---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ + + +Subsystems can also be tracked using the events namespace. Currently, there are three trackable subsystems: Dispatcher, Life Preserver, and System State. +The following is a template to subscribe to various subsystem event notifications: + +**Websocket Request** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "subscribe", + "id" : "sampleID", + "args" : ["dispatcher", "life-preserver", "system-state"] + } + +Once subscribed, events will be received as they are produced. To unsubscribe from events, repeat the request, using "unsubscribe" for the "name". + +Here is an example reply from the Life Preserver subsystem: + +**Websocket Reply** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "life-preserver", + "id" : "" + "args" : { + "message" : , + "priority" : " - + ", + "class" : "[snapshot/replication]" + } + } + +Dispatcher +---------- + +The Dispatcher subsystem is used by sysadm to process external commands and return specific information from the utility. +This is managed on the server as a separate process, and will not interrupt primary server tasks. +To subscribe to the Dispatcher subsystem for event updates, use the following: + +**Websocket Request** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "subscribe", + "id" : "sampleID", + "args" : ["dispatcher"] + } + +Dispatcher has two different kinds of websocket messages, general process notifications and specialized subsystem process notifications. +The general process notifications will appear as follows: + +**Websocket Event Message (Process Starting)** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "process_id" : "", + "state" : "running" + } + } + +.. + .. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + +**Websocket Event Message (Process Complete)** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "time_finished" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "finished", + "return_codes" + } + } + +Particular classes within sysadm may return information through the Dispatcher events system. These types of messages are slightly different in output format, which is noted here: + +**Websocket Event Message** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "dispatcher", + "id" : "none", + "args" : { + "event_system" : /, + "state" : "running" OR "finished", + + "process_details" : { + "time_started" : , + "cmd_list" : [ "", ""], + "process_id" : "", + "state" : "running" + } + } + } + +For specific details on these special types of events please refer to the Classes section of this User Guide. + +Life Preserver +-------------- + +To subscribe to the Life Preserver subsystem for event updates, use the following: + +**Websocket Request** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "subscribe", + "id" : "sampleID", + "args" : ["life-preserver"] + } + +**Websocket Event Message** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "life_preserver", + "id" : "none", + "args" : { + "message" : "", + "priority" : "", + "class" : "snapshot" OR "replication" + } + } + +System State +------------ + +To subscribe to the System State subsystem for event updates, use the following: + +**Websocket Request** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "subscribe", + "id" : "sampleID", + "args" : ["system-state"] + } + +**Websocket Event Message** + +.. code-block:: json + + { + "namespace" : "events", + "name" : "system_state", + "id" : "none", + "args" : { + "hostname" : "", + "hostnamechanged" : "true", (only if host name changed) + "zpools" : { + "" : { + "size" : "<107G>", + "alloc" : "<13.1G>", + "free" : "<93.9G>", + "frag" : "<6%>", + "expandsz" : "<->", + "dedup" : "<1.00x>", + "altroot" : "<->", + "capacity" : "<12%>", + "health" : "", + "priority" : "" (if error) + } + } + } + } + \ No newline at end of file