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

Review server handbook:

Browse Source 
- Rewrite Introduction section for clarity.
- Add references to other SysAdm handbooks.
- Fix whitespace issues in all files.
- Fix numerous errors in all files.
- Add note about the current WIP nature of SysAdm.
- Add note listing current default ports SysAdm needs to be opened for remote access to work.
  Also noted the user can redefine which ports SysAdm uses.
This commit is contained in:
Mrt134
2016-09-06 10:57:30 -04:00
parent a1dfac0392
commit 49fb902581
3 changed files with 79 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/server_handbook/basics.rst
View File

@@ -3,7 +3,7 @@
Getting Started
===============
Beginning with SysAdm™ is a relatively simple process.
Beginning with SysAdm™ is a relatively simple process.
SysAdm™ files are currently available from the
`github repository <https://github.com/trueos/sysadm>`_
@@ -12,7 +12,7 @@ SysAdm™ files are currently available from the
Building SysAdm™
----------------
Several Qt Modules are required before attempting to build
Several Qt Modules are required before attempting to build
SysAdm™:
.. code-block:: none
@@ -21,7 +21,7 @@ SysAdm™:
Qt5 Concurrent (# pkg install qt5-concurrent)
Qt5 Websockets (# pkg install qt5-websockets)
Building the prototype version of SysAdm™ assumes you have access to
Building the prototype version of SysAdm™ assumes you have access to
github.com.
.. code-block:: none
@@ -36,7 +36,7 @@ github.com.
Starting SysAdm™
----------------
SysAdm™ can be started one of two ways: the traditional rc(8)
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)
@@ -51,7 +51,6 @@ To run under rc(8)
% sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES"
% sudo service sysadm-rest start
To run under jobd(8)
.. code-block:: none
@@ -62,6 +61,15 @@ To run under jobd(8)
(Optional for REST)
% sudo jobctl org.pcbsd.sysadm-rest enable
.. danger:: Several ports on the system firewall will need to be opened
for SysAdm™ to have remote access functionality:
* Port 12149 for WebSocket interaction.
* Port 12150 for the REST interface.
* Port 12151 for the SysAdm™ bridge server.
The user can also designate their own ports for SysAdm™.
.. _bridge init:
Bridge Initialization
@@ -75,7 +83,7 @@ process for a new user to configure their client to communicate with the
now configured server and bridge.
.. tip:: A list of current commands is available by typing :command:`-h`
after the utility name (Example: :command:`sysadm-bridge -h`).
after the utility name (Example: :command:`sysadm-bridge -h`).
.. _serverbridge init:
@@ -87,9 +95,9 @@ To initialize the server and bridge, begin with the server. Run
This will export the public SSL key the server uses to authenticate with
the bridge.
.. 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.
.. 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
@@ -98,8 +106,8 @@ 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).
.. tip:: The bridge can import SSL files whether it is active or not
with no negative effects.
.. tip:: The bridge can import SSL files regardless of its active state
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
@@ -117,8 +125,8 @@ Adding a Client to the Server/Bridge Connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. 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.
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
@@ -146,11 +154,4 @@ 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.sysadm.us/.
bridge.

66
docs/server_handbook/introduction.rst
View File

@@ -1,10 +1,9 @@
.. _intro:
Introduction
============
**Preface**
**Preface**
Written by users of the SysAdm™ management utility.
@@ -12,25 +11,50 @@ Version |version|
Copyright © 2016 iXSystems®.
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.
Welcome to SysAdm™! This documentation is intended to educate the user
on initializing and configuring the SysAdm™ remote management options.
Initialization and management will be documented in two separate
chapters, :ref:`gettingstarted`, and :ref:`management`.
.. warning:: SysAdm™ is still under heavy development, and all
information contained in the documentation is subject to change.
**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™.
SysAdm™ is a middleware utility designed to streamline system management
with options for both local and remote access.
.. note:: By default, SysAdm™ does **not** allow for remote access.
The user must configure the system to allow this feature.
One unique element to SysAdm™ is how the middleware is designed to
modify the system directly. SysAdm™ has no middleware database, which
means all changes made with SysAdm™ modify the system configuration
files directly, resulting in a system administrator no longer needing to
log into a system via SSH or relearn system management. SysAdm™ "speaks"
the same language, allowing for simple and effective system
administration.
For remote access, SysAdm™ is being designed to route encrypted traffic
through a "bridge", a static announcement server which facilitates
communication between the user's controlling device and the remote
access system.
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 it can not be used to
record or alter critical information flow.
**Would you like to know more?**
Documentation for the SysAdm™ project is split amongst three handbooks:
* **API Reference Guide**: A library of all API calls and WebSocket
requests for SysAdm™. This reference is constantly updated as new API
calls are written. It can be found at https://api.sysadm.us/.
* **Client Handbook**: A detailed guide to all client side functions
of SysAdm™.
* **Server Handbook**: A basic guide to initializing SysAdm™ with
a bridge and server connection.

24
docs/server_handbook/manage.rst
View File

@@ -1,14 +1,14 @@
.. _management:
SysAdm™ Management
==================
Managing SysAdm™
================
SysAdm™ comes with a standard configuration file located at
SysAdm™ comes with a standard configuration file located in
:file:`/usr/local/etc/sysadm.conf.dist`.
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™
It is possible to edit this file for a custom configuration, but the
result will need to be saved as :file:`sysadm.conf`. Here are the
current default settings for SysAdm™:
.. code-block:: none
@@ -27,14 +27,14 @@ This default configuration also has blacklist options:
### Blacklist options ###
# - Number of minutes that an IP remains on the blacklist
BLACKLIST_BLOCK_MINUTES=60
# - Number of authorization failures before an IP is placed on the
# - Number of authorization failures before an IP is placed on the
blacklist
BLACKLIST_AUTH_FAIL_LIMIT=5
# - Number of minutes of no activity from an IP before resetting the
# - Number of minutes of no activity from an IP before resetting the
failure counter
# (Note: A successful authorization will always reset the fail
# (Note: A successful authorization will always reset the fail
counter)
BLACKLIST_AUTH_FAIL_RESET_MINUTES=10
Please note these default options are subject to change as the SysAdm™
Please note these default options are subject to change as the SysAdm™
utility is developed.