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

Merge branch 'master' of github.com:pcbsd/sysadm

Browse Source
This commit is contained in:
Ken Moore
2016-02-29 14:43:36 -05:00
parent 3663931eb7 187b1cc3e3
commit ef6f7ec39f
2 changed files with 59 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@@ -18,7 +18,8 @@
Official repo for PC-BSD's sysadm middleware WebSocket & REST server
This middleware acts as the core for controlling a PC-BSD or FreeBSD <br />
system either locally or remotely via WebSockets or REST.
system either locally or remotely via WebSockets or REST. It is also the <br />
server component to [PC-BSD's SysAdm GUI client](https://github.com/pcbsd/sysadm-ui-qt).
### Required Qt Modules
@@ -41,12 +42,12 @@ Qt5 Websockets (pkg install qt5-websockets)
```
(For WebSockets - Required for SysAdm Client)
% sudo sysrc -f /etc/rc.conf sysadm_websocket_enable="YES"
% sudo service sysadm-websocket start
% sudo sysrc -f /etc/rc.conf sysadm_enable="YES"
% sudo service sysadm start
(Optional for REST)
% sudo sysrc -f /etc/rc.conf sysadm_restserver_enable="YES"
% sudo service sysadm-restserver start
% sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES"
% sudo service sysadm-rest start
```
### API Documentation

64
api/connection.rst
View File

@@ -13,12 +13,8 @@ Add some links to docs on websockets and json....
Authentication
==============
Describe how to authenticate to websockets via Local / Remote, local connections do not need username / password...
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 authentciation class
request contains the following parameters:
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:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
@@ -38,7 +34,9 @@ request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
Several methods are available for authentication. Here is an example of a login using a username and password:
Several methods are available for authentication. Here is an example of a login using a username and password.
.. note:: when connecting to the localhost, the password field may be left empty for non-root user access.
**WebSocket Request**
@@ -69,6 +67,50 @@ Here is an example of using token authentication, where the token is invalidated
}
}
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)**
.. code-block:: json
{
"namespace" : "rpc",
"name" : "auth_ssl",
"id" : "sampleID",
"args" : ""
}
**WebSocket Reply (Stage 1)**
.. code-block:: json
{
"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)**
.. code-block:: json
{
"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**
@@ -85,9 +127,9 @@ 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 after 10 minutes of inactivity.
.. 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 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:
@@ -192,4 +234,4 @@ A query contains the following parameters:
"id": "fooid",
"name": "response",
"namespace": "rpc"
}
}