diff --git a/docs/api_reference/classes/logs.rst b/docs/api_reference/classes/logs.rst index 9c3d28c..ede9e95 100644 --- a/docs/api_reference/classes/logs.rst +++ b/docs/api_reference/classes/logs.rst @@ -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: diff --git a/docs/api_reference/conf.py b/docs/api_reference/conf.py index 16cee56..a203fc4 100644 --- a/docs/api_reference/conf.py +++ b/docs/api_reference/conf.py @@ -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) diff --git a/docs/api_reference/connection.rst b/docs/api_reference/connection.rst index 46ed8a4..c4cd3b5 100644 --- a/docs/api_reference/connection.rst +++ b/docs/api_reference/connection.rst @@ -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. diff --git a/docs/api_reference/themes/trueos_style/static/css/trueos_style.css b/docs/api_reference/themes/trueos_style/static/css/trueos_style.css index 9343c59..cab5dae 100644 --- a/docs/api_reference/themes/trueos_style/static/css/trueos_style.css +++ b/docs/api_reference/themes/trueos_style/static/css/trueos_style.css @@ -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*/ diff --git a/docs/client_handbook/_static/trueos_style/static/css/trueos_style.css b/docs/client_handbook/_static/trueos_style/static/css/trueos_style.css index 9343c59..cab5dae 100644 --- a/docs/client_handbook/_static/trueos_style/static/css/trueos_style.css +++ b/docs/client_handbook/_static/trueos_style/static/css/trueos_style.css @@ -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*/ diff --git a/docs/client_handbook/conf.py b/docs/client_handbook/conf.py index 9e115dd..75efc52 100644 --- a/docs/client_handbook/conf.py +++ b/docs/client_handbook/conf.py @@ -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) diff --git a/docs/server_handbook/basics.rst b/docs/server_handbook/basics.rst index ff28939..856a075 100644 --- a/docs/server_handbook/basics.rst +++ b/docs/server_handbook/basics.rst @@ -4,23 +4,27 @@ Getting Started =============== Beginning with SysAdm™ is a relatively simple process. -SysAdm™ files are currently available from the `github repository `_ - +SysAdm™ files are currently available from the +`github repository `_ .. _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 `, -replacing and 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 `, +replacing and 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 ` -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 ` for the +Moving to the bridge, as the administrator (or root), run +:command:`sysadm-bridge import_ssl_file ` 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 []` -to import the client -> server SSL key file. This grants an individual -with that specific SSL authorization the same permissions as . +to import the client -> server SSL key file. This grants an individual +with the specific SSL authorization the same permissions as . -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/. \ No newline at end of file diff --git a/docs/server_handbook/conf.py b/docs/server_handbook/conf.py index 0475ece..38c8973 100644 --- a/docs/server_handbook/conf.py +++ b/docs/server_handbook/conf.py @@ -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) diff --git a/docs/server_handbook/introduction.rst b/docs/server_handbook/introduction.rst index 17e62db..e7a716f 100644 --- a/docs/server_handbook/introduction.rst +++ b/docs/server_handbook/introduction.rst @@ -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™. \ No newline at end of file diff --git a/docs/server_handbook/manage.rst b/docs/server_handbook/manage.rst index 1e6ca11..ac59104 100644 --- a/docs/server_handbook/manage.rst +++ b/docs/server_handbook/manage.rst @@ -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 diff --git a/docs/server_handbook/themes/trueos_style/static/css/trueos_style.css b/docs/server_handbook/themes/trueos_style/static/css/trueos_style.css index 9343c59..cab5dae 100644 --- a/docs/server_handbook/themes/trueos_style/static/css/trueos_style.css +++ b/docs/server_handbook/themes/trueos_style/static/css/trueos_style.css @@ -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*/