mirror of
https://github.com/outbackdingo/sysadm.git
synced 2026-01-27 10:20:26 +00:00
Merge pull request #9 from Mrt134/master
Working on section 3 of PC-BSD API 1.0 documentation.
This commit is contained in:
Dru Lavigne
@@ -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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"state" : "running"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.. index:: listisos, iohyve
|
||||
|
||||
.. _List ISOs:
|
||||
|
||||
@@ -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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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"
|
||||
}
|
||||
}
|
||||
|
||||
**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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"state" : "running"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"state" : "running"
|
||||
}
|
||||
}
|
||||
}
|
||||
231
api/events.rst
Normal file
231
api/events.rst
Normal file
@@ -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" : "<none>"
|
||||
"args" : {
|
||||
"message" : <message>,
|
||||
"priority" : "<number> -
|
||||
<category>",
|
||||
"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" : "<some id string>",
|
||||
"state" : "running"
|
||||
}
|
||||
}
|
||||
|
||||
..
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"namespace" : "events",
|
||||
"name" : "dispatcher",
|
||||
"id" : "none",
|
||||
"args" : {
|
||||
"time_started" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"state" : "running"
|
||||
}
|
||||
}
|
||||
|
||||
**Websocket Event Message (Process Complete)**
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"namespace" : "events",
|
||||
"name" : "dispatcher",
|
||||
"id" : "none",
|
||||
"args" : {
|
||||
"time_finished" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : <namespace>/<name>,
|
||||
"state" : "running" OR "finished",
|
||||
<Other fields depending on subsystem>
|
||||
"process_details" : {
|
||||
"time_started" : <ISO 8601 time date string>,
|
||||
"cmd_list" : [ "<command 1>", "<command 2>"],
|
||||
"process_id" : "<some id string>",
|
||||
"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" : "<text string>",
|
||||
"priority" : "<number - warning level>",
|
||||
"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" : "<name>",
|
||||
"hostnamechanged" : "true", (only if host name changed)
|
||||
"zpools" : {
|
||||
"<poolname>" : {
|
||||
"size" : "<107G>",
|
||||
"alloc" : "<13.1G>",
|
||||
"free" : "<93.9G>",
|
||||
"frag" : "<6%>",
|
||||
"expandsz" : "<->",
|
||||
"dedup" : "<1.00x>",
|
||||
"altroot" : "<->",
|
||||
"capacity" : "<12%>",
|
||||
"health" : "<online>",
|
||||
"priority" : "<priority>" (if error)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user