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

SysAdm PEP8 Conversion

Browse Source 
- Converted SysAdm Server Handbook to PEP8 standards.
- Converted SysAdm API Handbook to PEP8 standards.
This commit is contained in:
Mrt134
2016-07-05 18:26:39 -04:00
parent 4da94971cc
commit 4bf475bdc6
17 changed files with 731 additions and 376 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
docs/basics.rst
View File

@@ -12,7 +12,8 @@ SysAdm™ files are currently available from the `github repository <https://git
Building SysAdm™
----------------
The following Qt Modules are required before attempting to build SysAdm™: ::
The following Qt Modules are required before attempting to build
SysAdm™: ::
Qt5 Core (# pkg install qt5-core)
Qt5 Concurrent (# pkg install qt5-concurrent)
@@ -20,7 +21,8 @@ The following Qt Modules are required before attempting to build SysAdm™: ::
Qt5 Sql (# pkg install qt5-sql)
Qt5 Websockets (# pkg install qt5-websockets)
Building the prototype version of SysAdm™ assumes you have access to github.com. ::
Building the prototype version of SysAdm™ assumes you have access to
github.com. ::
% git clone https://github.com/pcbsd/sysadm.git
% cd sysadm/src
@@ -32,7 +34,8 @@ Building the prototype version of SysAdm™ assumes you have access to github.co
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: 1. The traditional rc(8)
mechanism 2. The new jobd(8) mechanism
To run under rc(8)::
@@ -58,40 +61,84 @@ 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 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.
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` after the utility name (Example: :command:`sysadm-bridge -h`).
.. note:: A list of current commands is available by typing :command:`-h`
after the utility name (Example: :command:`sysadm-bridge -h`).
.. _serverbridge init:
Server and Bridge Initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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 finding those files for import to the bridge.
.. note:: For both server and client, giving SSL key files an easy to
remember name and location will 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 bridge (if not already running).
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
bridge (if not already running).
.. note:: The bridge can import SSL files whether it is active or not with no negative effects.
.. note:: 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 server through the bridge.
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
server through the bridge.
.. _add client:
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 prior to proceeding with the client initialization process.
.. 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
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 :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.
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.
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.
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.
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>.
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>.
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 "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.
.. _adddoc:

24
docs/introduction.rst
View File

@@ -12,10 +12,26 @@ 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.
.. 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.
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.

20
docs/manage.rst
View File

@@ -3,10 +3,12 @@
SysAdm™ Management
==================
SysAdm™ comes with a standard configuration file located at :file:`/usr/local/etc/sysadm.conf.dist`.
SysAdm™ comes with a standard configuration file located at
: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 is 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 :kbd:`sysadm.conf`. Here are the current
default settings for SysAdm™::
#Sample Configuration file for the sysadm server
@@ -21,10 +23,14 @@ This default configuration also has blacklist options, recreated here::
### 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 blacklist
# - 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 failure counter
# (Note: A successful authorization will always reset the fail counter)
# - Number of minutes of no activity from an IP before resetting the
failure counter
# (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™ utility is developed.
Please note these default options are subject to change as the SysAdm™
utility is developed.