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 index 3d3c498..22cde3e 100644 --- a/api/events.rst +++ b/api/events.rst @@ -1,11 +1,12 @@ .. _Events: Events -****** +====== -The "events" namespace can be used to setup and receive asyncronous updates about system status and other types of system notifications. +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 asyncronous events. For this reason, only Websocket examples are used in this section. +.. 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: @@ -26,7 +27,9 @@ Every events request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -Here is an example of subscribing to Life Preserver events: + +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** @@ -36,12 +39,12 @@ Here is an example of subscribing to Life Preserver events: "namespace" : "events", "name" : "subscribe", "id" : "sampleID", - "args" : ["dispatcher", "life-preserver"] + "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: +Here is an example reply from the Life Preserver subsystem: **Websocket Reply** @@ -59,3 +62,170 @@ Here is an example reply: } } +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