From 7ec47963ac04df70e4a7d6032fec5192a62e5b03 Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Wed, 24 Aug 2016 15:57:57 -0400 Subject: [PATCH] Begin in-depth review of API Reference guide. - 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). --- docs/api_reference/classes/beadm.rst | 73 ++-- docs/api_reference/classes/dispatcher.rst | 48 +-- docs/api_reference/classes/fs.rst | 38 +-- docs/api_reference/classes/iocage.rst | 108 +++--- docs/api_reference/connection.rst | 399 +++++++++++----------- docs/api_reference/events.rst | 96 +++--- 6 files changed, 380 insertions(+), 382 deletions(-) diff --git a/docs/api_reference/classes/beadm.rst b/docs/api_reference/classes/beadm.rst index 3a65226..464a512 100644 --- a/docs/api_reference/classes/beadm.rst +++ b/docs/api_reference/classes/beadm.rst @@ -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** diff --git a/docs/api_reference/classes/dispatcher.rst b/docs/api_reference/classes/dispatcher.rst index 956b6fd..6afb3b8 100644 --- a/docs/api_reference/classes/dispatcher.rst +++ b/docs/api_reference/classes/dispatcher.rst @@ -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** diff --git a/docs/api_reference/classes/fs.rst b/docs/api_reference/classes/fs.rst index c76f6b0..943ae66 100644 --- a/docs/api_reference/classes/fs.rst +++ b/docs/api_reference/classes/fs.rst @@ -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 diff --git a/docs/api_reference/classes/iocage.rst b/docs/api_reference/classes/iocage.rst index 4fc47fb..6535034 100644 --- a/docs/api_reference/classes/iocage.rst +++ b/docs/api_reference/classes/iocage.rst @@ -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) `_. +`iocage(8) `_. -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** :: diff --git a/docs/api_reference/connection.rst b/docs/api_reference/connection.rst index c4cd3b5..ec73b35 100644 --- a/docs/api_reference/connection.rst +++ b/docs/api_reference/connection.rst @@ -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 "" value is base64 encoded. + +.. note:: The "" 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" : "" } } - + **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" : "" } } - + **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 " ", - 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" - } + } \ No newline at end of file diff --git a/docs/api_reference/events.rst b/docs/api_reference/events.rst index 5a01182..45b3768 100644 --- a/docs/api_reference/events.rst +++ b/docs/api_reference/events.rst @@ -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. \ No newline at end of file +.. 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. \ No newline at end of file