From 2f5321ea75b2c89eeeb26a97aa4ac4c20b93a530 Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Tue, 31 May 2016 15:03:32 -0400 Subject: [PATCH 1/3] Sysadm server handbook section addition - Added WIP section "Bridge System Initialization" to server handbook - Divided instructions into two methods - one for complete ground up and another for allowing user access to an established network. - Began clarifying and testing instructions. --- docs/basics.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/basics.rst b/docs/basics.rst index 7b6dc63..045489e 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -45,6 +45,54 @@ Please note that it is possible to enable SysAdm™ to function in both states s % sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" % sudo service sysadm-rest start +.. _bridge sysinit: + +Bridge System Initialization +---------------------------- + +Initializing the bridge system will be described through two different methods: ground-up initialization and client/system administration. Ground-up will be useful for users who have full control over their network and are building and initializing SysAdm™ from scratch. The client/system administration method assumes a user is attempting to connect to an existing bridge which a system administrator controls. + +**Ground-Up Initialization** + +.. note:: This will require the latest server/bridge/client from source (on various systems as necessary) + +1. (Client) If you have a pre-existing SSL certificate bundle for the client, it will need to be removed (:command:`~/.config/PCBSD/sysadm_ssl*`). Then create a new SSL certificate bundle within the client after a restart, as the client will now create several different certificates. +2. (Client) Once the new SSL certs are created, open up the "Setup SSL -> View Certificates" page/tab in the connection manager, and click the "Save to file" button on both certs. This will export your public SSL key in file form, and place the files either in your Desktop folder or in your home directory (depending on the system/OS). +3. (Server) Run :command:`sudo sysadm-binary bridge_export_key [optional absolute file path]` to export the public SSL key that the server will use to authenticate with the bridge (it helps to dump it to a file like "/tmp/sysadm-server-to-bridge.key"). +4. (Bridge) Run (as the user which will be running the bridge) :command:`sysadm-bridge -import_ssl_file ` on the server -> bridge and client -> bridge key files that were exported earlier. If needed, these files can easily be transferred between systems. +5. (Bridge) If the bridge is not already running, start it now. Step 4 can be performed while the bridge is active without any adverse effects. +6. (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 . +7. (Server) Run :command:`sudo sysadm-binary bridge_add ` to point the server at a bridge. The bridge runs on **port 12149** by default, so you will probably need to add a ":12149" to the end (example: 127.0.0.1:12149). +8. (Server) If necessary, start/restart the server. If you view the log (/var/log/sysadm-server-ws.log) you should see some messages about connecting to the bridge. +9. (Client) Open up the connection Manager and create a connection to the bridge with the same URL as the one you just used for the server (Ex: 127.0.0.1:12149). The username/password are not needed, but the GUI will still ask for them anyway so you can just give it dummy info right now so you can test/connect. + +The bridge will 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 connected to that system through the bridge. + +**Client/System Administration** + +This method reflects a different scenario in which a user requests bridge access from a system administrator, who then adds the user's key to an existing bridge: +Two files are output client to bridge and client to server + +**User:** + +1. In the SysAdm client, create a SSL certificate bundle. Skip this step if the bundle has already been created. +2. Open the "Setup SSL -> View Certificates" page/tab in the connection manager, and click the "Save to file" button on both certificates. This will export your public SSL keys in file form, and place the files either in your Desktop folder or in your home directory (depending on the system/OS). +3. Contact the bridge's system administrator, requesting access to the bridge and providing the public SSL keys saved in step 1. + +**System Administrator:** + +1. Once a user request for bridge access is received along with the user generated public SSL keys, the administrator needs to add the keys to the server and bridge: + + a. Export the user submitted keys to their respective locations: client --> bridge and server --> bridge. + b. On the bridge, run :command:`sysadm-bridge -import_ssl_file ` on the server -> bridge and client -> bridge key files that were exported earlier. If needed, these files can easily be transferred between systems. + c. Back 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 . + +2. Provide the bridge URL to the user. + +**User:** + +1. In the SysAdm client, open up the connection Manager and create a connection to the bridge with the same URL as the one provided by the system administrator (Ex: 127.0.0.1:12149). +2. Provide a username/password if necessary. .. _adddoc: From 4a51c050d4cf29639d5133e6dc3e156d8fa508fb Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Thu, 2 Jun 2016 14:30:23 -0400 Subject: [PATCH 2/3] Rework bridge initialization - Reworked bridge initialization section for clarity - fixed a css error in the handbook theme --- docs/basics.rst | 55 ++++++++----------- .../pcbsd_style/static/css/pcbsd_style.css | 26 +++++---- 2 files changed, 37 insertions(+), 44 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index 045489e..6ece666 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -45,54 +45,43 @@ Please note that it is possible to enable SysAdm™ to function in both states s % sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" % sudo service sysadm-rest start -.. _bridge sysinit: +.. _bridge init: -Bridge System Initialization ----------------------------- +Bridge Initialization +--------------------- -Initializing the bridge system will be described through two different methods: ground-up initialization and client/system administration. Ground-up will be useful for users who have full control over their network and are building and initializing SysAdm™ from scratch. The client/system administration method assumes a user is attempting to connect to an existing bridge which a system administrator controls. +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 to for a new user to add their client to the now configured server and bridge. -**Ground-Up Initialization** +.. _serverbridge init: -.. note:: This will require the latest server/bridge/client from source (on various systems as necessary) +Server and Bridge Initialization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. (Client) If you have a pre-existing SSL certificate bundle for the client, it will need to be removed (:command:`~/.config/PCBSD/sysadm_ssl*`). Then create a new SSL certificate bundle within the client after a restart, as the client will now create several different certificates. -2. (Client) Once the new SSL certs are created, open up the "Setup SSL -> View Certificates" page/tab in the connection manager, and click the "Save to file" button on both certs. This will export your public SSL key in file form, and place the files either in your Desktop folder or in your home directory (depending on the system/OS). -3. (Server) Run :command:`sudo sysadm-binary bridge_export_key [optional absolute file path]` to export the public SSL key that the server will use to authenticate with the bridge (it helps to dump it to a file like "/tmp/sysadm-server-to-bridge.key"). -4. (Bridge) Run (as the user which will be running the bridge) :command:`sysadm-bridge -import_ssl_file ` on the server -> bridge and client -> bridge key files that were exported earlier. If needed, these files can easily be transferred between systems. -5. (Bridge) If the bridge is not already running, start it now. Step 4 can be performed while the bridge is active without any adverse effects. -6. (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 . -7. (Server) Run :command:`sudo sysadm-binary bridge_add ` to point the server at a bridge. The bridge runs on **port 12149** by default, so you will probably need to add a ":12149" to the end (example: 127.0.0.1:12149). -8. (Server) If necessary, start/restart the server. If you view the log (/var/log/sysadm-server-ws.log) you should see some messages about connecting to the bridge. -9. (Client) Open up the connection Manager and create a connection to the bridge with the same URL as the one you just used for the server (Ex: 127.0.0.1:12149). The username/password are not needed, but the GUI will still ask for them anyway so you can just give it dummy info right now so you can test/connect. +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. -The bridge will 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 connected to that system through 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. -**Client/System Administration** +Now, we must transition to the bridge to import this token. Login to the bridge as the administrator (or root), then type :command:`sysadm-bridge -import_ssl_file ` to import the server key file. If not already active, start the bridge now. -This method reflects a different scenario in which a user requests bridge access from a system administrator, who then adds the user's key to an existing bridge: -Two files are output client to bridge and client to server +.. note:: The bridge can import SSL files whether it is active or not with no negative effects. -**User:** +Moving back to 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 to the end (Example URL: 127.0.0.1:12149). If necessary, (re)start the server. The log (:file:`/var/log/sysadm-server-ws.log`) should display messages about connecting to the bridge. +The server and bridge should now be configured and communicating with each other. Now we can begin to add clients which will communicate with the server through the bridge. -1. In the SysAdm client, create a SSL certificate bundle. Skip this step if the bundle has already been created. -2. Open the "Setup SSL -> View Certificates" page/tab in the connection manager, and click the "Save to file" button on both certificates. This will export your public SSL keys in file form, and place the files either in your Desktop folder or in your home directory (depending on the system/OS). -3. Contact the bridge's system administrator, requesting access to the bridge and providing the public SSL keys saved in step 1. +.. _add client: -**System Administrator:** +Adding a Client to the Server/Bridge Connection +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -1. Once a user request for bridge access is received along with the user generated public SSL keys, the administrator needs to add the keys to the server and bridge: +.. 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. - a. Export the user submitted keys to their respective locations: client --> bridge and server --> bridge. - b. On the bridge, run :command:`sysadm-bridge -import_ssl_file ` on the server -> bridge and client -> bridge key files that were exported earlier. If needed, these files can easily be transferred between systems. - c. Back 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 . - -2. Provide the bridge URL to the user. +In the client UI, create or manage the SSL 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 "Save to File" 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 your system administrator as part of a request for server/bridge access. -**User:** +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. -1. In the SysAdm client, open up the connection Manager and create a connection to the bridge with the same URL as the one provided by the system administrator (Ex: 127.0.0.1:12149). -2. Provide a username/password if necessary. +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 . + +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: diff --git a/docs/themes/pcbsd_style/static/css/pcbsd_style.css b/docs/themes/pcbsd_style/static/css/pcbsd_style.css index a845f3f..f9aa33c 100644 --- a/docs/themes/pcbsd_style/static/css/pcbsd_style.css +++ b/docs/themes/pcbsd_style/static/css/pcbsd_style.css @@ -2698,10 +2698,10 @@ div[class^='highlight'] pre { font-weight: bold; position: relative; // background: #fcfcfc; - background: #808991 !important; + background: rgba(0, 0, 0, 0) linear-gradient(135deg, #b5bdc8 0%, #828c95 36%, #28343b 100%)!important; border: none; - border-bottom: solid 1px #808991; - border-top: solid 1px #808991; + border-bottom: none/*solid 1px #808991*/; + border-top: none/*solid 1px #808991*/; padding-left: 1.618em -4px } .wy-menu-vertical li.on a:hover, @@ -2734,7 +2734,11 @@ div[class^='highlight'] pre { /*level3:#.#.#*/.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a { display: block; // background: #c9c9c9; - background: #850d0d; + background: rgb(179,19,5); +background: -moz-linear-gradient(top, rgba(179,19,5,1) 0%, rgba(179,19,5,1) 100%); +background: -webkit-linear-gradient(top, rgba(179,19,5,1) 0%,rgba(179,19,5,1) 100%); +background: linear-gradient(to bottom, rgba(179,19,5,1) 0%,rgba(179,19,5,1) 100%); +filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#b31305', endColorstr='#b31305',GradientType=0 ); padding: 0.4045em 4.045em } .wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand { @@ -2841,7 +2845,7 @@ div[class^='highlight'] pre { } .wy-side-nav-search>a:hover, .wy-side-nav-search .wy-dropdown>a:hover { - background: rgba(255, 255, 255, 0.1) none repeat scroll 0 0 + background: rgba(255, 255, 255, 0.1) none repeat scroll 0 0; } .wy-side-nav-search>a img.logo, .wy-side-nav-search .wy-dropdown>a img.logo { @@ -2905,7 +2909,7 @@ div[class^='highlight'] pre { top: 0; bottom: 0; left: 0; - padding-bottom: 2em; + padding-bottom: .1em; width: 300px; overflow-x: hidden; overflow-y: hidden; @@ -3622,11 +3626,11 @@ span[id*='MathJax-Span'] { .wy-nav-side, div.related { - background: #a90329; - background: -moz-linear-gradient(top, #a90329 0%, #8f0222 44%, #6d0019 100%); - background: -webkit-linear-gradient(top, #a90329 0%,#8f0222 44%,#6d0019 100%); - background: linear-gradient(to bottom, #a90329 0%,#8f0222 44%,#6d0019 100%); - filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#a90329', endColorstr='#6d0019',GradientType=0 ); + background: rgb(179,19,5); +background: -moz-linear-gradient(top, rgba(179,19,5,1) 0%, rgba(179,19,5,1) 100%); +background: -webkit-linear-gradient(top, rgba(179,19,5,1) 0%,rgba(179,19,5,1) 100%); +background: linear-gradient(to bottom, rgba(179,19,5,1) 0%,rgba(179,19,5,1) 100%); +filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#b31305', endColorstr='#b31305',GradientType=0 ); /* was 0f0df0 */ } code.kbd, From e184d4b9d65bfe110e6cccbe50aa4705efc96ead Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Thu, 2 Jun 2016 15:02:17 -0400 Subject: [PATCH 3/3] Updated "starting sysadm" section - Updated Starting SysAdm section to reflect current instructions - Fixed a couple grammar and spelling errors in the Bridge Initialization section --- docs/basics.rst | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/docs/basics.rst b/docs/basics.rst index 6ece666..4f752df 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -32,25 +32,33 @@ Building the prototype version of SysAdm™ assumes you have access to github.co Starting SysAdm™ ---------------- -SysAdm™ has two functioning states, WebSockets (preferred) and REST. -Websockets allow the client to stay connected over a long period of time, allowing the usage of notifications and events. -The REST server mode is more limited as it only allows the user to send and receive single messages over a short term connection. -Please note that it is possible to enable SysAdm™ to function in both states simultaneously. :: - - (Websocket - recommended) - % sudo sysrc -f /etc/rc.conf sysadm_enable="YES" - % sudo service sysadm start +SysAdm can be started one of two ways: 1. The traditional rc(8) mechanism 2. The new jobd(8) mechanism - (Optional for REST) - % sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" - % sudo service sysadm-rest start +To run under rc(8):: + + (For WebSockets - Required for SysAdm Client) + % sudo sysrc -f /etc/rc.conf sysadm_enable="YES" + % sudo service sysadm start + + (Optional for REST) + % sudo sysrc -f /etc/rc.conf sysadm_rest_enable="YES" + % sudo service sysadm-rest start + + +To run under jobd(8):: + + (For WebSockets - Required for SysAdm Client) + % sudo jobctl org.pcbsd.sysadm enable + + (Optional for REST) + % sudo jobctl org.pcbsd.sysadm-rest enable .. _bridge init: 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 to for a new user to add their client to 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. .. _serverbridge init: @@ -61,12 +69,12 @@ To initialize the server and bridge, begin with the server. Run :command:`sudo s .. 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 this token. Login to the bridge as the administrator (or root), then type :command:`sysadm-bridge -import_ssl_file ` to import the server key file. If not already active, start the bridge now. +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 bridge (if not already running). .. note:: The bridge can import SSL files whether it is active or not with no negative effects. -Moving back to 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 to the end (Example URL: 127.0.0.1:12149). If necessary, (re)start the server. The log (:file:`/var/log/sysadm-server-ws.log`) should display messages about connecting to the bridge. -The server and bridge should now be configured and communicating with each other. Now we can begin to add clients which will communicate with the server through the bridge. +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 server through the bridge. .. _add client: @@ -75,7 +83,7 @@ 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. -In the client UI, create or manage the SSL 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 "Save to File" 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 your 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 "Save to File" 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 ` 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.