From 49fb90258152c419c824987289feb7045481cbfc Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Tue, 6 Sep 2016 10:57:30 -0400 Subject: [PATCH] Review server handbook: - 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. --- docs/server_handbook/basics.rst | 43 ++++++++--------- docs/server_handbook/introduction.rst | 66 ++++++++++++++++++--------- docs/server_handbook/manage.rst | 24 +++++----- 3 files changed, 79 insertions(+), 54 deletions(-) diff --git a/docs/server_handbook/basics.rst b/docs/server_handbook/basics.rst index 856a075..1b0372c 100644 --- a/docs/server_handbook/basics.rst +++ b/docs/server_handbook/basics.rst @@ -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 `_ @@ -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 and 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 ` 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/. \ No newline at end of file +bridge. \ No newline at end of file diff --git a/docs/server_handbook/introduction.rst b/docs/server_handbook/introduction.rst index e7a716f..941873a 100644 --- a/docs/server_handbook/introduction.rst +++ b/docs/server_handbook/introduction.rst @@ -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™. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/server_handbook/manage.rst b/docs/server_handbook/manage.rst index ac59104..cf9de15 100644 --- a/docs/server_handbook/manage.rst +++ b/docs/server_handbook/manage.rst @@ -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. \ No newline at end of file