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

Update API with Bridge

Browse Source 
- Identified server, client or bridge websocket requests
- Added Bridge subsystem section with json example
This commit is contained in:
Mrt134
2016-05-12 16:05:25 -04:00
parent 8a16f9a4d0
commit 1a45554b8a
3 changed files with 115 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
api/conf.py
View File

@@ -91,7 +91,7 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'classic'
html_theme = 'pcbsd_style'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -99,7 +99,7 @@ html_theme = 'classic'
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
html_theme_path = ['themes/']
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
@@ -120,7 +120,7 @@ html_theme = 'classic'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.

173
api/connection.rst
View File

@@ -40,99 +40,105 @@ class request contains the 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 username/password requests are server side only.
Several methods are available for authentication. Here is an example of a login using a username and password.
.. note:: individual servers can be configured to refuse username and password requests altogether.
**1. Username and Password:**
**WebSocket Request: (Server only)**
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth",
"id" : "sampleID",
"args" : {
"username" : "myuser",
"password" : "mypassword"
}
}
.. note:: when connecting to the localhost, the password field may be left empty for non-root user access.
**WebSocket Request**
**2. Token Authentication: (Server only)**
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth",
"id" : "sampleID",
"args" : {
"username" : "myuser",
"password" : "mypassword"
}
}
Here is an example of using token authentication, where the token is invalidated after 5 minutes of inactivity:
**WebSocket Request**
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth_token",
"id" : "sampleID",
"args" : {
{
"namespace" : "rpc",
"name" : "auth_token",
"id" : "sampleID",
"args" : {
"token" : "MySavedAuthToken"
}
}
}
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.
**WebSocket Request (Stage 1 - Initial Request)**
**3. SSL Certificate: (Server and Bridge)**
.. code-block:: json
**WebSocket Request (Stage 1 - Initial Request)**
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth_ssl",
"id" : "sampleID",
"args" : ""
}
{
"namespace" : "rpc",
"name" : "auth_ssl",
"id" : "sampleID",
"args" : ""
}
**WebSocket Reply (Stage 1)**
**WebSocket Reply (Stage 1)**
.. code-block:: json
.. code-block:: json
{
"args": {
"test_string" : "<some random plaintext string of letters/numbers>"
},
"id": "sampleID",
"name": "response",
"namespace": "rpc"
}
{
"args": {
"test_string" : "<some random plaintext string of letters/numbers>"
},
"id": "sampleID",
"name": "response",
"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 accurate transport
back to the server.
**WebSocket Request (Stage 2 - Return Encoded String)**
**WebSocket Request (Stage 2 - Return Encoded String)**
.. code-block:: json
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth_ssl",
"id" : "sampleID",
"args" : {
"encrypted_string" : "<base64-encoded string>"
{
"namespace" : "rpc",
"name" : "auth_ssl",
"id" : "sampleID",
"args" : {
"encrypted_string" : "<base64-encoded string>"
}
}
}
A successful authentication will provide a reply similar to this:
**WebSocket Reply**
**WebSocket Reply**
.. code-block:: json
.. code-block:: json
{
"args": [
{
"args": [
"SampleAuthenticationToken",
300
],
"id": "sampleID",
"name": "response",
"namespace": "rpc"
}
],
"id": "sampleID",
"name": "response",
"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
@@ -142,30 +148,30 @@ An invalid authentication, or a system request after the user session has timed
**WebSocket Reply**
.. code-block:: json
.. code-block:: json
{
"args": {
{
"args": {
"code": 401,
"message": "Unauthorized"
},
"id": "sampleID",
"name": "error",
"namespace": "rpc"
}
},
"id": "sampleID",
"name": "error",
"namespace": "rpc"
}
To clear a pre-saved authentication token, such as signing out, use this request:
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth_clear",
"id" : "sampleID",
"args" : "junk argument"
}
{
"namespace" : "rpc",
"name" : "auth_clear",
"id" : "sampleID",
"args" : "junk argument"
}
.. _SSL Certificate Management:
@@ -340,10 +346,11 @@ Dispatcher events have the following syntax:
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
PUT /rpc/dispatcher
{
"action" : "run",
"procID2" : [
@@ -443,16 +450,16 @@ The rest of this section provides examples of the available *names* for each typ
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 access the user has.
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**
.. code-block:: json
PUT /rpc/query
{
PUT /rpc/query
{
"junk" : "junk"
}
}
**REST Response**
@@ -503,7 +510,7 @@ An RPC query can be issued to probe all the known subsystems and return which on
Identify Subsystem
------------------
To identify the type of SysAdm system, use "identify". Possible identities are "server", "bridge", and "client".
To identify the type of SysAdm system, use :command:`identify`. Possible identities are "server", "bridge", and "client," with all three system types using this subsystem.
**REST Request**
@@ -543,7 +550,7 @@ To identify the type of SysAdm system, use "identify". Possible identities are "
List SSL Checksums
------------------
Use "list_ssl_checksums" to 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**

23
api/events.rst
View File

@@ -191,6 +191,7 @@ To subscribe to the Life Preserver subsystem for event updates, use the followin
}
}
System State
------------
@@ -234,4 +235,24 @@ To subscribe to the System State subsystem for event updates, use the following:
}
}
}
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 server connects/disconnects or vice versa.
**Websocket Reply: Connected Bridge**
.. code-block:: json
{
"id" : "",
"namespace" : "events",
"name" : "bridge",
"args" : {
"available_connections" : ["ID1", "ID2", "<etc..>"]
}
}
.. 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.