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

Style and arrow patch update + general review of API and Server handbooks.

Browse Source 
- Updated trueos_style to current.
- Updated menuselection arrow replacement patch to current.
- Reviewed API reference guide:
  - Reviewed for :guilabel: additions.
  - Added missing trademark symbols.
- Update Server handbook:
  - Added missing trademaks.
  - Replaced outdated link.
  - Updated admonition boxes.
  - Added :guilabel: role where necessary.
  - Add more descriptive text of SysAdm and the goals of the project.
  - Updated code-boxes.
This commit is contained in:
Mrt134
2016-08-24 13:13:57 -04:00
parent 9ed043f0f5
commit cf4a485382
11 changed files with 106 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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)

6
docs/api_reference/connection.rst
View File

@@ -21,7 +21,7 @@ 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
the SysAdm™ service. Every authentication class request contains the
following parameters:
+----------------+------------+---------------------------------------+
@@ -613,7 +613,7 @@ mind:
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:
+---------------------------------+---------------+------------------------------------------------------------------------------+
@@ -705,7 +705,7 @@ 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
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.

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*/