github-personal/sysadm
1
0
Fork 0
mirror of https://github.com/outbackdingo/sysadm.git synced 2026-01-27 10:20:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Begin in-depth review of API Reference guide.

Browse Source 
- Whitespace fixes.
- Reworking text.
- Reducing the size of tables for better PEP8 conformity.
- Altering admonition box titles (use tip and danger).
- Update roles (use :guilabel: and verify other uses).
This commit is contained in:
Mrt134
2016-08-24 15:57:57 -04:00
parent cf4a485382
commit 7ec47963ac
6 changed files with 380 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/api_reference/classes/beadm.rst
View File

@@ -7,25 +7,26 @@ The beadm class is used to manage boot environments.
Every beadm class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | beadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "listbes", "renamebe", "activatebe", "createbe", "destroybe", "mountbe", and "umountbe" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+----------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+----------------------------------------+
| name | beadm | |
| | | |
+---------------+-----------+----------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+----------------------------------------+
| action | | Supported actions include "listbes", |
| | | "renamebe", "activatebe", "createbe", |
| | | "destroybe", "mountbe", and "umountbe" |
+---------------+-----------+----------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listbes, beadm
@@ -34,12 +35,11 @@ for each type of request, along with their responses.
List Boot Environments
======================
The "listbes" action retrieves the list of boot environments. For each
boot environment, the response includes its name, its flags (where "R"
The "listbes" action retrieves the list of boot environments. For each
boot environment, the response includes its name, its flags (where "R"
is active on reboot, "N" is active now and "-" is inactive), the date it
was created, its mount point, its nickname, and its size.
**REST Request**
::
@@ -89,7 +89,7 @@ was created, its mount point, its nickname, and its size.
"name": "response",
"namespace": "sysadm"
}
.. index:: renamebe, beadm
.. _Rename a Boot Environment:
@@ -98,10 +98,9 @@ Rename a Boot Environment
=========================
The "renamebe" action renames the specified boot environment. When using
this action, specify the new name as the "source" and the boot
this action, specify the new name as the "source" and the boot
environment as the "target".
**REST Request**
::
@@ -143,7 +142,7 @@ environment as the "target".
"name": "response",
"namespace": "sysadm"
}
.. index:: activatebe, beadm
.. _Activate Boot Environment:
@@ -151,10 +150,9 @@ environment as the "target".
Activate Boot Environment
=========================
The "activatebe" action activates the specified boot environment
The "activatebe" action activates the specified boot environment
(target) so that it will be the default at next boot.
**REST Request**
::
@@ -193,7 +191,7 @@ The "activatebe" action activates the specified boot environment
"name": "response",
"namespace": "sysadm"
}
.. index:: createbe, beadm
.. _Create Boot Environment:
@@ -201,9 +199,9 @@ The "activatebe" action activates the specified boot environment
Create Boot Environment
=======================
The "create" action creates a new boot environment. Specify the name of
the boot environment as the "newbe". By default, this action clones the
active boot environment. To specify another, inactive boot environment,
The "create" action creates a new boot environment. Specify the name of
the boot environment as the "newbe". By default, this action clones the
active boot environment. To specify another, inactive boot environment,
also include "clonefrom" to specify which boot environment to clone from.
**REST Request**
@@ -247,7 +245,7 @@ also include "clonefrom" to specify which boot environment to clone from.
"name": "response",
"namespace": "sysadm"
}
.. index:: destroybe, beadm
.. _Destroy a Boot Environment:
@@ -255,10 +253,9 @@ also include "clonefrom" to specify which boot environment to clone from.
Destroy a Boot Environment
==========================
The "destroybe" action destroys the specified "target" boot environment
The "destroybe" action destroys the specified "target" boot environment
and forcefully unmounts it.
**REST Request**
::
@@ -297,7 +294,7 @@ and forcefully unmounts it.
"name": "response",
"namespace": "sysadm"
}
.. index:: mountbe, beadm
.. _Mount a Boot Environment:
@@ -305,7 +302,7 @@ and forcefully unmounts it.
Mount a Boot Environment
========================
The "mountbe" action mounts the specified boot environment. Use the
The "mountbe" action mounts the specified boot environment. Use the
optional "mountpoint" argument to specify the mount point.
**REST Request**
@@ -349,7 +346,7 @@ optional "mountpoint" argument to specify the mount point.
"name": "response",
"namespace": "sysadm"
}
.. index:: umountbe, beadm
.. _Unmount a Boot Environment:
@@ -357,7 +354,7 @@ optional "mountpoint" argument to specify the mount point.
Unmount a Boot Environment
==========================
The "umountbe" action forcibly unmounts the specified boot environment,
The "umountbe" action forcibly unmounts the specified boot environment,
even if it is in use.
**REST Request**

48
docs/api_reference/classes/dispatcher.rst
View File

@@ -3,30 +3,30 @@
dispatcher
**********
The dispatcher class is used to spin up external processes on demand,
The dispatcher class is used to spin up external processes on demand,
such as a user running a custom system setup script.
Every dispatcher class request contains the following parameters:
Every dispatcher class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | dispatcher | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | rpc | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "list", "kill" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+------------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+============+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+------------+--------------------------------------+
| name | dispatcher | |
| | | |
+---------------+------------+--------------------------------------+
| namespace | rpc | |
| | | |
+---------------+------------+--------------------------------------+
| action | | Actions include "list" and "kill". |
| | | |
+---------------+------------+--------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list, dispatcher
@@ -35,8 +35,8 @@ for each type of request, along with their responses.
List Processes
==============
The "list" action lists all the currently running or pending processes
within the dispatcher queues. Possible queues are "no_queue",
The "list" action lists all the currently running or pending processes
within the dispatcher queues. Possible queues are "no_queue",
"pkg_queue", and "iocage_queue".
**REST Request**
@@ -83,7 +83,7 @@ within the dispatcher queues. Possible queues are "no_queue",
"name": "response",
"namespace": "rpc"
}
.. index:: kill, dispatcher
.. _Kill Processes:
@@ -91,7 +91,7 @@ within the dispatcher queues. Possible queues are "no_queue",
Kill Processes
==============
The "kill" action allows a user with full access to cancel pending or
The "kill" action allows a user with full access to cancel pending or
running jobs within the dispatcher system.
**REST Request**

38
docs/api_reference/classes/fs.rst
View File

@@ -5,27 +5,27 @@ fs
The fs class is used to manage the files and directories on the system.
Every fs class request contains the following parameters:
Every fs class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | fs | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "dirlist" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+--------------------------------------+
| name | fs | |
| | | |
+---------------+-----------+--------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+--------------------------------------+
| action | | Actions include "dirlist". |
| | | |
+---------------+-----------+--------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: dirlist, fs

108
docs/api_reference/classes/iocage.rst
View File

@@ -3,33 +3,35 @@
iocage
******
The iocage class is used to manage jails which provide a light-weight,
operating system-level virtualization for running applications or
The iocage class is used to manage jails, which provide a light-weight,
operating system-level virtualization for running applications or
services.
Every iocage class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | iocage | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "getdefaultsettings", "listjails", "getjailsettings", "df", "startjail", "stopjail", |
| | | "capjail", "clonejail", "createjail", "destroyjail", "execjail", "cleanjails", "cleanreleases", "cleantemplates", |
| | | "cleanall", "activatepool", and "deactivatepool" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+======================================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+------------------------------------------------------+
| name | iocage | |
| | | |
+---------------+-----------+------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+------------------------------------------------------+
| action | | Actions include "activatepool", "capjail", |
| | | "cleanall", "cleanjails", "cleanreleases", |
| | | "cleantemplates", "clonejail", "createjail", |
| | | "deactivatepool", "destroyjail", "df", |
| | | "execjail", "getdefaultsettings", "getjailsettings", |
| | | "listjails", "startjail", and "stopjail". |
+---------------+-----------+------------------------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: getdefaultsettings, iocage
@@ -38,7 +40,7 @@ for each type of request, along with their responses.
Default Settings
================
The "getdefaultsettings" action lists all of the global settings that
The "getdefaultsettings" action lists all of the global settings that
apply to all jails.
**REST Request**
@@ -318,10 +320,10 @@ List Jails
==========
The "listjails" action lists information about currently installed jails.
For each jail, the response includes the UUID of the jail, whether or
not the jail has been configured to start at system boot, the jail ID
(only applies to running jails), whether or not the jail is running, a
friendly name for the jail (tag), and the type of jail (basejail or
For each jail, the response includes the UUID of the jail, whether or
not the jail has been configured to start at system boot, the jail ID
(only applies to running jails), whether or not the jail is running, a
friendly name for the jail (tag), and the type of jail (basejail or
thickjail).
**REST Request**
@@ -394,16 +396,16 @@ thickjail).
Jail Settings
=============
The "getjailsettings" action lists settings that apply to the specified
The "getjailsettings" action lists settings that apply to the specified
jail. This action supports 4 modes:
* specify a property and a jail
* Specify a property and a jail.
* specify a property and *-r* for all downloaded releases
* Specify a property and *-r* for all downloaded releases.
* specify *all* properties for the specified jail
* Specify *all* properties for the specified jail.
* specify the jail
* Specify the jail.
Here is an example of specifying the property and the jail:
@@ -659,7 +661,7 @@ jail, as both modes produce identical outputs:
"name": "response",
"namespace": "sysadm"
}
.. index:: df, iocage
.. _List Resource Usage:
@@ -667,9 +669,9 @@ jail, as both modes produce identical outputs:
List Resource Usage
===================
The "df" action lists resource usage for all jails. For each jail, the
response includes: CRT (compression ratio), RES (reserved space), QTA
(disk quota), USE (used space), AVA (available space), and TAG (jail
The "df" action lists resource usage for all jails. For each jail, the
response includes: CRT (compression ratio), RES (reserved space), QTA
(disk quota), USE (used space), AVA (available space), and TAG (jail
name).
**REST Request**
@@ -723,7 +725,7 @@ name).
"name": "response",
"namespace": "sysadm"
}
.. index:: startjail, iocage
.. _Start a Jail:
@@ -733,7 +735,7 @@ Start a Jail
The "startjail" action starts the specified jail.
.. note:: A jail can be started only once. If the jail is already
.. warning:: A jail can be started only once. If the jail is already
running, an error message will be generated.
**REST Request**
@@ -792,7 +794,7 @@ The "startjail" action starts the specified jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: stopjail, iocage
.. _Stop a Jail:
@@ -802,7 +804,7 @@ Stop a Jail
The "stopjail" action stops the specified jail.
.. note:: A jail can be only stopped once. If the jail has already
.. warning:: A jail can be only stopped once. If the jail has already
stopped, an error message will be generated.
**REST Request**
@@ -863,7 +865,7 @@ The "stopjail" action stops the specified jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: capjail, iocage
.. _Cap a Jail:
@@ -871,7 +873,7 @@ The "stopjail" action stops the specified jail.
Cap a Jail
===========
The "capjail" action re-applies resource limits to a running jail. Use
The "capjail" action re-applies resource limits to a running jail. Use
this action when you make a change to the specified jail's resources and
want to apply the changes without restarting the jail.
@@ -913,7 +915,7 @@ want to apply the changes without restarting the jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: clonejail, iocage
.. _Clone a Jail:
@@ -921,13 +923,13 @@ want to apply the changes without restarting the jail.
Clone a Jail
============
The "clonejail" action clones the specified "jail". By default, the
clone will inherit that jail's properties. Use "props" to specify any
The "clonejail" action clones the specified "jail". By default, the
clone will inherit that jail's properties. Use "props" to specify any
properties that should differ. All available properties are described in
`iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
`iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
In this example, the "tag" property is specified so that the new jail
has a different name than the jail it was cloned from.
In this example, the "tag" property is specified so that the new jail
has a different name than the jail it was cloned from.
**REST Request**
@@ -973,7 +975,7 @@ has a different name than the jail it was cloned from.
"name": "response",
"namespace": "sysadm"
}
In this example, no properties are specified so iocage populates its own
values and the props returned in the response is empty:
@@ -1019,7 +1021,7 @@ values and the props returned in the response is empty:
"name": "response",
"namespace": "sysadm"
}
.. index:: createjail, iocage
.. _Create a Jail:
@@ -1027,11 +1029,13 @@ values and the props returned in the response is empty:
Create a Jail
=============
The "createjail" action creates a jail.
The "createjail" action creates a jail.
In this example, the "tag" property sets the name of the new jail and
In this example, the "tag" property sets the name of the new jail and
the "release" property specifies which template to use.
.. TODO CONTINUE EDITING BELOW------------------------------------------
**REST Request**
::

399
docs/api_reference/connection.rst
View File

@@ -4,24 +4,24 @@ Getting Started
***************
Welcome to the SysAdm™ API (application programming interface)
documentation handbook! SysAdm™ is a complex utility with many integral
subsystems and classes, and this handbook will attempt to guide a new
user through the initialization, core features, and intricacies of the
utility.
Reference Guide! SysAdm™ is a complex utility with many integral
subsystems and classes, and this reference guide will attempt to
accurately represent the initialization, core features, and intricacies
of the utility.
This handbook will be heavily utilizing the Websocket specification and
JSON (JavaScript Object Notation) format. For detailed descriptions of
these items, please refer to their respective websites at
http://www.websocket.org and http://json.org/.
This handbook will be heavily utilizing the Websocket specification and
JSON (JavaScript Object Notation) format. For detailed descriptions of
these items, please refer to their respective websites at
http://www.websocket.org and http://json.org/.
.. _Authentication:
Authentication
==============
Once a websocket connection is made to the server, the client needs to
use the authentication class to authenticate itself to obtain access to
the SysAdm™ service. Every authentication class request contains the
Once a websocket connection is made to the server, the client needs to
use the authentication class to authenticate itself to obtain access to
the SysAdm™ service. Every authentication class request contains the
following parameters:
+----------------+------------+---------------------------------------+
@@ -43,17 +43,17 @@ following parameters:
+----------------+------------+---------------------------------------+
There are three options for server authentication: username and password,
token authentication, and pre-registered SSL certifications. SSL
certification requests are handled by both server and bridge, while
token authentication, and pre-registered SSL certifications. SSL
certification requests are handled by both server and bridge, while
token authentication and username/password requests are server side only.
.. note:: individual servers can be configured to refuse username and
.. tip:: Individual servers can be configured to refuse username and
password requests altogether.
**1. Username and Password:**
**WebSocket Request: (Server only)**
.. code-block:: json
{
@@ -66,13 +66,13 @@ token authentication and username/password requests are server side only.
}
}
.. note:: when connecting to the localhost, the password field may be
.. tip:: When connecting to the localhost, the password field may be
left empty for non-root user access.
**2. Token Authentication: (Server only)**
**WebSocket Request**
.. code-block:: json
{
@@ -84,15 +84,15 @@ token authentication and username/password requests are server side only.
}
}
Here is an example of using a pre-registered SSL certificate to request
authentication. Note that this is a two-step process with only a 30
seconds window of validity, so this is best left to automated systems
Here is an example of using a pre-registered SSL certificate to request
authentication. Note that this is a two-step process with only a 30
seconds window of validity, so this is best left to automated systems
rather than direct user requests.
**3.1. SSL Certificate Authentication: (Server and Bridge)**
**WebSocket Request (Stage 1 - Initial Request)**
.. code-block:: json
{
@@ -115,11 +115,11 @@ rather than direct user requests.
"namespace": "rpc"
}
On receipt of the "test_string", the user-side client must encrypt that
string with the desired SSL certificate/key combination, then return
that encrypted string back to the server (Stage 2) within 30 seconds of
the initial stage 1 reply. The encrypted string should also be
base64-encoded before insertion into the stage 2 JSON request to ensure
On receipt of the "test_string", the user-side client must encrypt that
string with the desired SSL certificate/key combination, then return
that encrypted string back to the server (Stage 2) within 30 seconds of
the initial stage 1 reply. The encrypted string should also be
base64-encoded before insertion into the stage 2 JSON request to ensure
accurate transport back to the server.
**WebSocket Request (Stage 2 - Return Encoded String)**
@@ -135,7 +135,7 @@ accurate transport back to the server.
}
}
A successful authentication will provide a reply similar to this:
A successful authentication will provide a similar reply:
**WebSocket Reply**
@@ -151,17 +151,17 @@ A successful authentication will provide a reply similar to this:
"namespace": "rpc"
}
.. note:: the first element of the "args" array is the authentication
token for use later as necessary, while the second element is
the number of seconds for which that token is valid. The token
is reset after every successful communication with the
websocket. In this example, it is set to 5 minutes of
inactivity before the token is invalidated. The websocket
server is currently set to close any connection to a client
.. note:: The first element of the "args" array is the authentication
token for later use, while the second element is
the number of seconds the token will remain valid. The token
is reset after every successful communication with the
websocket. In this example, it is set to 5 minutes of
inactivity before the token is invalidated. The websocket
server is currently set to close any connection to a client
after 10 minutes of inactivity.
An invalid authentication, or a system request after the user session
has timed out due to inactivity, looks like this:
An invalid authentication or a system request after the user session
has timed out due to inactivity will have a specific message:
**WebSocket Reply**
@@ -177,8 +177,7 @@ has timed out due to inactivity, looks like this:
"namespace": "rpc"
}
To clear a pre-saved authentication token, such as signing out, use this
request:
To clear a pre-saved authentication token, such as signing out:
**WebSocket Request**
@@ -196,11 +195,11 @@ request:
**3.2. Alternate SSL Certificate Authentication Initiation (server
through bridge)**
This is an alternate method for stage 1 of the SSL Certificate
Authentication method. In this case, the initial request has specified
using a base 64 encoded key, to which the server will respond with its
own encrypted message. This prevents the bridge from being able to
decrypt messages between client and server for the duration of the
This is an alternate method for stage 1 of the SSL Certificate
Authentication method. In this case, the initial request has specified
using a base 64 encoded key, to which the server will respond with its
own encrypted message. This prevents the bridge from being able to
decrypt messages between client and server for the duration of the
connection.
**WebSocket Request (Stage 1 - Initial Request)**
@@ -233,16 +232,15 @@ connection.
}
.. important:: in the above reply, both values for "test_string" and
"new_ssl_key" are encrypted with the public SSL key
matching the md5 sum from the initial request and then
base 64 encoded for transport. All future messages are
bulk encrypted with the "new_ssl_key", which is a new
randomly generated private key only known to the server
and client. For example, the following section {"id",
"name","namespace","args"} will now be encrypted with the
private key in one block prior to transport through the
bridge.
.. danger:: In the reply above, both values for "test_string" and
"new_ssl_key" are encrypted with the public SSL key matching
the md5 sum from the initial request and then base 64
encoded for transport. All future messages are bulk
encrypted with the "new_ssl_key", which is a new randomly
generated private key only known to the server and client.
For example, the following section {"id", "name",
"namespace","args"} will now be encrypted with the private
key in one block prior to transport through the bridge.
.. _SSL Certificate Management:
@@ -252,25 +250,25 @@ SSL Certificate Management
Several actions are available for managing the SSL certificates used for
authentication.
+---------------------------------+---------------+----------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+========================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------+
| name | settings | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------+
| action | | supported actions include "list_ssl_certs", "register_ssl_cert", and "revoke_ssl_cert" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------+
+---------------+-----------+---------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+=============================================+
| id | | Any unique value for the request; examples |
| | | include a hash, checksum, or uuid. |
+---------------+-----------+---------------------------------------------+
| name | settings | |
| | | |
+---------------+-----------+---------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+---------------------------------------------+
| action | | Actions include "list_ssl_certs", |
| | | "register_ssl_cert", and "revoke_ssl_cert". |
+---------------+-----------+---------------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list_ssl_certs, settings
@@ -279,15 +277,15 @@ for each type of request, along with their responses.
List SSL Certificates
---------------------
The "list_ssl_certificates" action lists the known and registered
certificates. For each certificate, the response includes the username,
The "list_ssl_certificates" action lists the known and registered
certificates. For each certificate, the response includes the username,
public key, and the certificate's details.
**Websocket Request**
.. code-block:: json
{
{
"id" : "example_id",
"name" : "settings",
"namespace": "sysadm",
@@ -299,8 +297,8 @@ public key, and the certificate's details.
**Websocket Response**
.. code-block:: json
{
{
"id" : "example_id",
"name" : "response",
"namespace": "sysadm",
@@ -310,8 +308,8 @@ public key, and the certificate's details.
}
}
}
.. note:: the "<key>" value is base64 encoded.
.. note:: The "<key>" value is base64 encoded.
.. index:: register_ssl_cert, settings
@@ -320,17 +318,17 @@ public key, and the certificate's details.
Register a SSL Certificate
--------------------------
The "register_ssl_certificate" action registers the specified
certificate on the server. Once registered, that user is allowed to
authenticate without a password as long as that same certificate is
loaded in any future connections. When using this action, The "pub_key"
needs to match the public key of one of the certificates currently
The "register_ssl_certificate" action registers the specified
certificate on the server. Once registered, a user is allowed to
authenticate without a password as long as that same certificate is
loaded in any future connections. When using this action, The "pub_key"
needs to match the public key of one of the certificates currently
loaded into the server/client connection.
**Websocket Request**
.. code-block:: json
{
"id" : "example_id",
"name" : "settings",
@@ -342,21 +340,20 @@ loaded into the server/client connection.
"email" : "<example_email>"
}
}
**Websocket Response**
.. code-block:: json
{
{
"id" : "example_id",
"name" : "response",
"namespace": "sysadm",
"args" : {}
}
.. note:: the "nickname" and "email" arguments are optional and may not
be seen in all responses
.. note:: The "nickname" and "email" arguments are optional, and may not
be seen in all responses.
.. index:: revoke_ssl_cert, settings
@@ -365,18 +362,18 @@ loaded into the server/client connection.
Revoke a SSL Certificate
------------------------
The "revoke_ssl_certificate" action revokes a currently registered
certificate so that it can no longer be used for authentication. The
"pub_key" must be specified and must match one of the keys given by the
The "revoke_ssl_certificate" action revokes a currently registered
certificate so that it can no longer be used for authentication. The
"pub_key" must be specified and must match one of the keys given by the
"list_ssl_certs" action, but does not need to match any currently loaded
certificates. The "user" is optional and allows a connection with full
administrative privileges to revoke a certificate belonging to another
certificates. The "user" is optional and allows a connection with full
administrative privileges to revoke a certificate belonging to another
user.
**Websocket Request**
.. code-block:: json
{
"id" : "example_id",
"name" : "settings",
@@ -387,65 +384,65 @@ user.
"user" : "<example_user>"
}
}
**Websocket Response**
.. code-block:: json
{
{
"id" : "example_id",
"name" : "response",
"namespace": "sysadm",
"args" : {}
}
.. note:: if the current user has full administrative access,
"list_ssl_certs" will return the registered certificates for
.. note:: If the current user has full administrative access,
"list_ssl_certs" will return the registered certificates for
all users on the system. Otherwise, it will only return the
certificates for the current user. Similarly,
"revoke_ssl_cert" may be used to remove certificates
registered to other users only if the current user/connection
certificates for the current user. Similarly,
"revoke_ssl_cert" may be used to remove certificates
registered to other users only if the current user/connection
has full administrative access; otherwise, it may only be used
to manage the current user's certificates.
.. index:: dispatcher, events
.. index:: dispatcher, events
.. _Dispatcher Subsystem:
Dispatcher Subsystem
====================
The dispatcher subsystem is designed for running external utilities or
scripts in an asynchronous fashion. Any connected client can subscribe
The dispatcher subsystem is designed for running external utilities or
scripts in an asynchronous fashion. Any connected client can subscribe
to per-connection event notifications about dispatcher processes through
the events system, but only users in the *wheel* group have the
authority to directly submit new jobs for the dispatcher.
the events system, but only users in the *wheel* group have the
authority to directly submit new jobs for the dispatcher.
.. note:: other subsystems may also use the dispatcher for long-running
processes in the background, and these subsystems may allow
non-wheel group users to perform these tasks as necessary.
Also, the events namespace does not really translate over to
REST which was not designed for asyncronous events. For this
.. note:: Other subsystems may also use the dispatcher for long-running
processes in the background, and these subsystems may allow
non-wheel group users to perform these tasks as necessary.
Also, 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.
The format of "dispatcher" event requests is as follows:
+---------------------------------+---------------+------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+==============================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| name | subscribe | use the desired action |
| | unsubscribe | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| namespace | events | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| args | dispatcher | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
+---------------+-------------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+=============+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-------------+--------------------------------------+
| name | subscribe | use the desired action |
| | unsubscribe | |
+---------------+-------------+--------------------------------------+
| namespace | events | |
| | | |
+---------------+-------------+--------------------------------------+
| args | dispatcher | |
| | | |
+---------------+-------------+--------------------------------------+
For example, to subscribe to dispatcher events:
@@ -458,11 +455,11 @@ For example, to subscribe to dispatcher events:
"args" : ["dispatcher"]
}
Once subscribed, the requested events will be received as they are
produced. To unsubscribe from event notifications, repeat the request,
using "unsubscribe" for the "name". For example, to unsubscribe from
Once subscribed, the requested events will be received as they are
produced. To unsubscribe from event notifications, repeat the request,
using "unsubscribe" for the "name". For example, to unsubscribe from
dispatcher events:
.. code-block:: json
{
@@ -486,30 +483,30 @@ This response indicates that a dispatcher event occurred:
}
}
A "dispatcher" query contains the following parameters:
A "dispatcher" query contains several parameters:
+---------------------------------+---------------+------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+==============================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| name | dispatcher | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| namespace | events | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| action | | "run" is used to submit process commands |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
+---------------+------------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+============+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+------------+--------------------------------------+
| name | dispatcher | |
| | | |
+---------------+------------+--------------------------------------+
| namespace | events | |
| | | |
+---------------+------------+--------------------------------------+
| action | | "run" submits process commands |
| | | |
+---------------+------------+--------------------------------------+
Dispatcher events have the following syntax:
**Websocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "events",
@@ -525,14 +522,16 @@ Dispatcher events have the following syntax:
}
}
Any user within the *wheel* group can use the "run" action to submit a
Any user within the *wheel* group can use the "run" action to submit a
new job to the dispatcher:
**REST Request**
:cmd: PUT /rpc/dispatcher
.. code-block:: json
.. code-block:: none
PUT /rpc/dispatcher
.. code-block:: json
{
"action" : "run",
@@ -545,7 +544,7 @@ new job to the dispatcher:
**REST Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -558,7 +557,7 @@ new job to the dispatcher:
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"name" : "dispatcher",
@@ -576,7 +575,7 @@ new job to the dispatcher:
**WebSocket Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -589,52 +588,52 @@ new job to the dispatcher:
"name": "response",
"namespace": "rpc"
}
When submitting a job to the dispatcher, keep the following points in
mind:
* Process commands are not the same as shell commands. A dispatcher
When submitting a job to the dispatcher, there are several points to
remember:
* Process commands are not the same as shell commands. A dispatcher
process command uses the syntax "<binary/utility> <list of arguments>",
similar to a simple shell command. However, complex shell operations
with pipes or test statements will not function properly within a
similar to a simple shell command. However, complex shell operations
with pipes or test statements will not function properly within a
dispatcher process.
* There are two types of jobs: a single string entry for simple commands,
and an array of strings for a chain of commands. A chain of commands
is treated as a single process, and the commands are run sequentially
until either a command fails (returns non-0 or the process crashes),
and an array of strings for a chain of commands. A chain of commands
is treated as a single process, and the commands are run sequentially
until either a command fails (returns non-0 or the process crashes),
or until there are no more commands to run.
* A chain of commands is useful for multi-step operations but is not
* A chain of commands is useful for multi-step operations but is not
considered a replacement for a good shell script on the server.
.. _Server Subsystems:
Server Subsystems
=================
The RPC namespace can be used to get information about SysAdm™ server
The RPC namespace can be used to get information about SysAdm™ server
subsystems. This namespace supports the following parameters:
+---------------------------------+---------------+------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+==============================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| name | | supported names are "query", "identify", and "list_ssl_checksums" |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| namespace | rpc | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| args | | can be any data |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
+---------------+-----------+------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+==========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+------------------------------------------+
| name | | Supported names are "query", "identify", |
| | | and "list_ssl_checksums" |
+---------------+-----------+------------------------------------------+
| namespace | rpc | |
| | | |
+---------------+-----------+------------------------------------------+
| args | | Can be any data. |
| | | |
+---------------+-----------+------------------------------------------+
The rest of this section provides examples of the available *names* for
each type of request, along with their responses.
The rest of this section provides examples of the available *names* for
each type of request, along with their responses.
.. index:: query, rpc
@@ -643,8 +642,8 @@ each type of request, along with their responses.
Query Subsystems
----------------
An RPC query can be issued to probe all the known subsystems and return
which ones are currently available and what level of read and write
An RPC query can be issued to probe all the known subsystems and return
which ones are currently available and what level of read and write
access the user has. This subsystem is used only by the server.
**REST Request**
@@ -704,9 +703,9 @@ access the user has. This subsystem is used only by the server.
Identify Subsystem
------------------
To identify the type of SysAdm™ system, use :command:`identify`. Possible
identities are "server", "bridge", and "client," with all three system
identities are "server", "bridge", and "client," with all three system
types using this subsystem.
**REST Request**
@@ -740,7 +739,7 @@ types using this subsystem.
"name": "response",
"namespace": "rpc"
}
.. index:: list_ssl_checksums, rpc
.. _List SSL Checksums:
@@ -748,8 +747,8 @@ types using this subsystem.
List SSL Checksums
------------------
Used by both server and client, :command:`list_ssl_checksums` will list
the MD5 checksums of all known SSL keys.
Used by both server and client, :command:`list_ssl_checksums` will list
the MD5 checksums of all known SSL keys.
**REST Request**
@@ -786,4 +785,4 @@ the MD5 checksums of all known SSL keys.
"id": "fooid",
"name": "response",
"namespace": "rpc"
}
}

96
docs/api_reference/events.rst
View File

@@ -3,37 +3,36 @@
Events
======
The "events" namespace can be used to setup and receive asynchronous
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.
.. warning:: 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:
Every events request contains several 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 |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
+---------------+-----------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+======================================+
| id | | Any unique value for the request, |
| | | including 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:
Subsystems can also be tracked using the events namespace. Currently,
there are three trackable subsystems: Dispatcher, Life Preserver, and
System State. Use the template to subscribe to various subsystem event
notifications:
**Websocket Request**
@@ -45,13 +44,13 @@ subsystem event notifications:
"id" : "sampleID",
"args" : ["dispatcher", "life-preserver", "system-state"]
}
Once subscribed, events will be received as they are produced. To
Once subscribed, events will be received as they are produced. To
unsubscribe from events, repeat the request, using "unsubscribe" for the
"name".
"name".
Here is an example reply from the Life Preserver subsystem:
**Websocket Reply**
.. code-block:: json
@@ -72,8 +71,8 @@ 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
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**
@@ -145,11 +144,10 @@ reflect the differences between these states:
}
}
Individual classes such as iohyve will move these dispatcher elements
into a "process_details" section. Tailored sample responses will be
provided in these classes' individual documentation pages. A generalized
sample is as follows:
Individual classes such as iohyve will move these dispatcher elements
into a "process_details" section. Tailored sample responses will be
provided in these classes' individual documentation pages. Here is a
generalized sample:
**Dispatcher Class Event Message**
@@ -167,13 +165,13 @@ sample is as follows:
}
}
For specific details on these special types of events please refer to
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
To subscribe to the Life Preserver subsystem for event updates, use the
following:
**Websocket Request**
@@ -201,12 +199,11 @@ following:
"class" : "snapshot/replication"
}
}
System State
------------
To subscribe to the System State subsystem for event updates, use the
To subscribe to the System State subsystem for event updates, use the
following:
**Websocket Request**
@@ -250,14 +247,14 @@ error has occurred.
}
}
}
Bridge
------
Bridge events are automatically received by any system connected to a
bridge, with no subscription required. This event will get sent out any
time a new connection/disconnection is made from the bridge which
impacts the current connection. A client will only get the event when a
Bridge events are automatically received by any system connected to a
bridge, with no subscription required. This event will get sent out any
time a new connection/disconnection is made from the bridge which
impacts the current connection. A client will only get the event when a
server connects/disconnects or vice versa.
**Websocket Reply: Connected Bridge**
@@ -273,6 +270,7 @@ server connects/disconnects or vice versa.
}
}
.. note:: Available_connections are **all** the connections available at
the time, **not** a difference from a previous state. There may be
both new ID's in the list and ID's which are no longer listed.
.. tip:: Available_connections are **all** the connections available at
the time, **not** a difference from a previous state. There may
be both new ID's in the list and ID's which are no longer
listed.