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:trueos/sysadm

Browse Source
This commit is contained in:
Ken Moore
2016-08-25 11:15:02 -04:00
parent 9f06fbb03c 7ec47963ac
commit c0ca7a333b
16 changed files with 484 additions and 481 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**
::

2
docs/api_reference/classes/logs.rst
View File

@@ -4,7 +4,7 @@ logs
****
The logs class is used to interact with the log files created by the
SysAdm server.
SysAdm™ server.
Every logs class request contains the following parameters:

2
docs/api_reference/conf.py
View File

@@ -95,7 +95,7 @@ from sphinx.roles import _amp_re
def patched_menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
if typ == 'menuselection':
text = text.replace('-->', u'\N{HEAVY WIDE-HEADED RIGHTWARDS ARROW}') # Here is the patch
text = text.replace('-->', u'\u2192') # Here is the patch
spans = _amp_re.split(text)

401
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
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**
@@ -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.

12
docs/api_reference/themes/trueos_style/static/css/trueos_style.css
View File

@@ -3679,21 +3679,19 @@ code.menuselection,
.guilabel,
.menuselection{
background-color: #D5DDE2; /* saturate from ecf0f3 to be more visible/blue on screen. */
display: inline-block;
display: inline;
font-family:'Inconsolata', monospace;
font-size: 95%;
padding-right: 3px;
padding-left: 3px;
padding-top: 3px;
padding-bottom: 2px;
border-radius: 5px;
line-height: 80%;
overflow: hidden;
padding-bottom: 3px;
border-radius: 3px;
overflow: hidden;
}
code.kbd, .kbd {
border: thin solid #000;
border-radius: 2px;
font-weight: bold
font-weight: bold
}
code.file, .file {
border: hidden/*thin solid #999*/

12
docs/client_handbook/_static/trueos_style/static/css/trueos_style.css
View File

@@ -3679,21 +3679,19 @@ code.menuselection,
.guilabel,
.menuselection{
background-color: #D5DDE2; /* saturate from ecf0f3 to be more visible/blue on screen. */
display: inline-block;
display: inline;
font-family:'Inconsolata', monospace;
font-size: 95%;
padding-right: 3px;
padding-left: 3px;
padding-top: 3px;
padding-bottom: 2px;
border-radius: 5px;
line-height: 80%;
overflow: hidden;
padding-bottom: 3px;
border-radius: 3px;
overflow: hidden;
}
code.kbd, .kbd {
border: thin solid #000;
border-radius: 2px;
font-weight: bold
font-weight: bold
}
code.file, .file {
border: hidden/*thin solid #999*/

3
docs/client_handbook/conf.py
View File

@@ -125,8 +125,7 @@ from sphinx.roles import _amp_re
def patched_menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
if typ == 'menuselection':
text = text.replace('-->', u'\N{HEAVY WIDE-HEADED RIGHTWARDS ARROW}') # Here is the patch
text = text.replace('-->', u'\u2192') # Here is the patch
spans = _amp_re.split(text)
node = nodes.literal(rawtext=rawtext)

115
docs/server_handbook/basics.rst
View File

@@ -4,23 +4,27 @@ Getting Started
===============
Beginning with SysAdm™ is a relatively simple process.
SysAdm™ files are currently available from the `github repository <https://github.com/trueos/sysadm>`_
SysAdm™ files are currently available from the
`github repository <https://github.com/trueos/sysadm>`_
.. _building:
Building SysAdm™
----------------
The following Qt Modules are required before attempting to build
SysAdm™: ::
Several Qt Modules are required before attempting to build
SysAdm™:
.. code-block:: none
Qt5 Core (# pkg install qt5-core)
Qt5 Concurrent (# pkg install qt5-concurrent)
Qt5 Websockets (# pkg install qt5-websockets)
Building the prototype version of SysAdm™ assumes you have access to
github.com. ::
github.com.
.. code-block:: none
% git clone https://github.com/trueos/sysadm.git
% cd sysadm/src
@@ -32,12 +36,14 @@ github.com. ::
Starting SysAdm™
----------------
SysAdm can be started one of two ways: 1. The traditional rc(8)
mechanism 2. The new jobd(8) mechanism
SysAdm™ can be started one of two ways: the traditional rc(8)
mechanism or using the new jobd(8) mechanism
To run under rc(8)::
To run under rc(8)
(For WebSockets - Required for SysAdm Client)
.. code-block:: none
(For WebSockets - Required for SysAdm™ Client)
% sudo sysrc -f /etc/rc.conf sysadm_enable="YES"
% sudo service sysadm start
@@ -46,9 +52,11 @@ To run under rc(8)::
% sudo service sysadm-rest start
To run under jobd(8)::
To run under jobd(8)
(For WebSockets - Required for SysAdm Client)
.. code-block:: none
(For WebSockets - Required for SysAdm™ Client)
% sudo jobctl org.pcbsd.sysadm enable
(Optional for REST)
@@ -59,14 +67,14 @@ To run under jobd(8)::
Bridge Initialization
---------------------
Configuring and connecting to a bridge can be a complicated process.
Thankfully, there are several steps that are done the first time a
server and bridge are configured with SysAdm but do not need to be
Configuring and connecting to a bridge can be a complicated process.
Thankfully, there are several steps that are done the first time a
server and bridge are configured with SysAdm™ but do not need to be
repeated later. Once these steps are complete, it becomes a much simpler
process for a new user to configure their client to communicate with the
now configured server and bridge.
.. note:: A list of current commands is available by typing :command:`-h`
.. tip:: A list of current commands is available by typing :command:`-h`
after the utility name (Example: :command:`sysadm-bridge -h`).
.. _serverbridge init:
@@ -74,33 +82,33 @@ now configured server and bridge.
Server and Bridge Initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To initialize the server and bridge, begin with the server. Run
To initialize the server and bridge, begin with the server. Run
:command:`sudo sysadm-binary bridge_export_key [optional absolute file path]`.
This will export the public SSL key the server uses to authenticate with
the bridge.
.. note:: For both server and client, giving SSL key files an easy to
remember name and location will simplify the process of
.. note:: For both server and client, give SSL key files an easy to
remember name and location to simplify the process of
finding those files for import to the bridge.
Now, we must transition to the bridge to import the server key. Login to
the bridge as the administrator (or root), then type
:command:`sysadm-bridge import_ssl_file <filename> <filepath>`,
replacing <filename> and <filepath> with the server key filename and
location. Once the server key file is successfully imported, start the
the bridge as the administrator (or root), then type
:command:`sysadm-bridge import_ssl_file <filename> <filepath>`,
replacing <filename> and <filepath> with the server key filename and
location. Once the server key file is successfully imported, start the
bridge (if not already running).
.. note:: The bridge can import SSL files whether it is active or not
.. tip:: The bridge can import SSL files whether it is active or not
with no negative effects.
Back on the server, run :command:`sudo sysadm-binary bridge_add <nickname> <URL>`
to point the server at the bridge. A bridge runs on **port 12149** by
default, so the URL will likely need **:12149** added on the end of the
address (Example URL: 127.0.0.1:12149). If necessary, (re)start the
server. The log (:file:`/var/log/sysadm-server-ws.log`) will display
messages about connecting to the bridge. If properly configured, the
server and bridge will now be communicating with each other. At this
point clients can be added to the mix which will communicate with the
to point the server at the bridge. A bridge runs on **port 12149** by
default, so the URL will likely need **:12149** added on the end of the
address (Example URL: 127.0.0.1:12149). If necessary, (re)start the
server. The log (:file:`/var/log/sysadm-server-ws.log`) will display
messages about connecting to the bridge. If properly configured, the
server and bridge will now be communicating with each other. At this
point, clients can be added to the mix which will communicate with the
server through the bridge.
.. _add client:
@@ -108,40 +116,41 @@ server through the bridge.
Adding a Client to the Server/Bridge Connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: If you have an old SSL bundle from a pre-alpha version of
SysAdm created before June 2016, it will need to be removed
.. danger:: If you have an old SSL bundle from a pre-alpha version of
SysAdm created before June 2016, it will need to be removed
prior to proceeding with the client initialization process.
In the client UI, create or import an SSL key bundle as prompted by the
UI. Once the new SSL keys are created, open
In the client UI, create or import an SSL key bundle as prompted by the
UI. Once the new SSL keys are created, open
:menuselection:`Setup SSL --> View Certificates` in the connection
manager and click "Export Public Key" for both the server and bridge
keys. This will export both SSL keys in file form, depositing them in
either the "Desktop" folder or home directory (depending on operating
system). If necessary, send these key files as an email attachment to
the system administrator as part of a request for server/bridge access.
manager and click :guilabel:`Export Public Key` for both the server and
bridge keys. This will export both SSL keys in file form, depositing
them in either the :file:`Desktop` folder or home directory (depending
on operating system). If necessary, send these key files as an email
attachment to the system administrator as part of a request for
server/bridge access.
Moving to the bridge, as the administrator (or root), run
:command:`sysadm-bridge import_ssl_file <nickname> <filepath>` for the
Moving to the bridge, as the administrator (or root), run
:command:`sysadm-bridge import_ssl_file <nickname> <filepath>` for the
requesting client's bridge key file. Now the client and bridge should be
able to communicate, but the client/server connection still needs to be
established.
able to communicate, but the client/server connection still needs to be
established.
On the server, run :command:`sudo sysadm-binary import_ssl_key <username> <filepath> [<email>]`
to import the client -> server SSL key file. This grants an individual
with that specific SSL authorization the same permissions as <user>.
to import the client -> server SSL key file. This grants an individual
with the specific SSL authorization the same permissions as <user>.
Back in the user client, open the connection manager and choose "Bridge
Relay" as the connection option. Input the established bridge's URL and
click "Connect".The bridge will now show up in the menu tree with a
different icon, and will have a sub-menu of connections within it. If
you click on the bridged system, it will open the standard UI but the
connection is still being relayed through the bridge.
Back in the user client, open the connection manager and choose
:guilabel:`Bridge Relay` as the connection option. Input the established
bridge's URL and click :guilabel:`Connect`. The bridge will now show up
in the menu tree with a different icon, and will have a sub-menu of
connections within it. Click on the bridged system to will open the
standard UI, but note the connection is still being relayed through the
bridge.
.. _adddoc:
Additional Documentation
------------------------
API documentation can be found at https://api.pcbsd.org .
API documentation can be found at https://api.sysadm.us/.

2
docs/server_handbook/conf.py
View File

@@ -95,7 +95,7 @@ from sphinx.roles import _amp_re
def patched_menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
if typ == 'menuselection':
text = text.replace('-->', u'\N{HEAVY WIDE-HEADED RIGHTWARDS ARROW}') # Here is the patch
text = text.replace('-->', u'\u2192') # Here is the patch
spans = _amp_re.split(text)

31
docs/server_handbook/introduction.rst
View File

@@ -12,26 +12,25 @@ Version |version|
Copyright © 2016 iXSystems®.
.. Intro Text WIP. Needed is a full description of what sysadm is and
what it can do. SysAdm is a middleware utility designed to provide a
user access to firewalled servers and systems from any location with
an open access point to the internet. To accomplish this goal, a
bridge device has been created, which relays all traffic between the
firewalled system and the user's controlling device. In order to
address security concerns, the bridge device is always considered
"untrusted" and several layers of encryption are added to all traffic
flowing through the bridge to ensure the bridge can not be used to
record or alter critical information flow. Once a secure connection
has been established, a user can fully control a firewalled system or
group of systems through the SysAdm utility. Installing packages,
creating work tasks, running build servers and automation;
controlling a secure system from any Internet connected location with
minimal risk of a security breach is the ultimate goal of SysAdm.
Welcome to SysAdm™! This documentation is intended to educate the user
on initializing and managing the SysAdm™ middleware. Initialization and
management will be documented in two separate chapters,
:ref:`gettingstarted`, and :ref:`management`. API documentation is being
handled at https://api.pcbsd.org.
**What is SysAdm™?**
SysAdm™ is a middleware utility designed to provide a user access to
firewalled servers and systems from any location with an open access
point to the internet. To accomplish this goal, a bridge device has been
created, which relays all traffic between the firewalled system and the
user's controlling device. In order to address security concerns, the
bridge device is always considered "untrusted" and several layers of
encryption are added to all traffic flowing through the bridge to ensure
the bridge can not be used to record or alter critical information flow.
Once a secure connection has been established, a user can fully control
a firewalled system or group of systems through the SysAdm™ utility.
Installing packages, creating work tasks, and managing build servers and
automation will all be possible once the utility is fully developed.
Controlling a secure system from any Internet connected device with
minimal risk of a security failure is the ultimate goal of SysAdm™.

10
docs/server_handbook/manage.rst
View File

@@ -8,9 +8,11 @@ SysAdm™ comes with a standard configuration file located at
It is possible to edit this file for a custom configuration, but the
result will need to be saved as :kbd:`sysadm.conf`. Here are the current
default settings for SysAdm™::
default settings for SysAdm™
#Sample Configuration file for the sysadm server
.. code-block:: none
#Sample Configuration file for the SysAdm™ server
### Server Port Number ###
# - Websocket Server (standard)
@@ -18,7 +20,9 @@ default settings for SysAdm™::
# - REST Server (started with the "-rest" CLI flag)
PORT_REST=12151
This default configuration also has blacklist options, recreated here::
This default configuration also has blacklist options:
.. code-block:: none
### Blacklist options ###
# - Number of minutes that an IP remains on the blacklist

12
docs/server_handbook/themes/trueos_style/static/css/trueos_style.css
View File

@@ -3679,21 +3679,19 @@ code.menuselection,
.guilabel,
.menuselection{
background-color: #D5DDE2; /* saturate from ecf0f3 to be more visible/blue on screen. */
display: inline-block;
display: inline;
font-family:'Inconsolata', monospace;
font-size: 95%;
padding-right: 3px;
padding-left: 3px;
padding-top: 3px;
padding-bottom: 2px;
border-radius: 5px;
line-height: 80%;
overflow: hidden;
padding-bottom: 3px;
border-radius: 3px;
overflow: hidden;
}
code.kbd, .kbd {
border: thin solid #000;
border-radius: 2px;
font-weight: bold
font-weight: bold
}
code.file, .file {
border: hidden/*thin solid #999*/