diff --git a/docs/api_reference/classes/beadm.rst b/docs/api_reference/classes/beadm.rst index 3a65226..464a512 100644 --- a/docs/api_reference/classes/beadm.rst +++ b/docs/api_reference/classes/beadm.rst @@ -7,25 +7,26 @@ The beadm class is used to manage boot environments. Every beadm class request contains several parameters: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | beadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| action | | supported actions include "listbes", "renamebe", "activatebe", "createbe", "destroybe", "mountbe", and "umountbe" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------+-----------+----------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+========================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-----------+----------------------------------------+ +| name | beadm | | +| | | | ++---------------+-----------+----------------------------------------+ +| namespace | sysadm | | +| | | | ++---------------+-----------+----------------------------------------+ +| action | | Supported actions include "listbes", | +| | | "renamebe", "activatebe", "createbe", | +| | | "destroybe", "mountbe", and "umountbe" | ++---------------+-----------+----------------------------------------+ -The rest of this section provides examples of the available *actions* -for each type of request, along with their responses. +The rest of this section provides examples of the available *actions* +for each type of request, along with their responses. .. index:: listbes, beadm @@ -34,12 +35,11 @@ for each type of request, along with their responses. List Boot Environments ====================== -The "listbes" action retrieves the list of boot environments. For each -boot environment, the response includes its name, its flags (where "R" +The "listbes" action retrieves the list of boot environments. For each +boot environment, the response includes its name, its flags (where "R" is active on reboot, "N" is active now and "-" is inactive), the date it was created, its mount point, its nickname, and its size. - **REST Request** :: @@ -89,7 +89,7 @@ was created, its mount point, its nickname, and its size. "name": "response", "namespace": "sysadm" } - + .. index:: renamebe, beadm .. _Rename a Boot Environment: @@ -98,10 +98,9 @@ Rename a Boot Environment ========================= The "renamebe" action renames the specified boot environment. When using -this action, specify the new name as the "source" and the boot +this action, specify the new name as the "source" and the boot environment as the "target". - **REST Request** :: @@ -143,7 +142,7 @@ environment as the "target". "name": "response", "namespace": "sysadm" } - + .. index:: activatebe, beadm .. _Activate Boot Environment: @@ -151,10 +150,9 @@ environment as the "target". Activate Boot Environment ========================= -The "activatebe" action activates the specified boot environment +The "activatebe" action activates the specified boot environment (target) so that it will be the default at next boot. - **REST Request** :: @@ -193,7 +191,7 @@ The "activatebe" action activates the specified boot environment "name": "response", "namespace": "sysadm" } - + .. index:: createbe, beadm .. _Create Boot Environment: @@ -201,9 +199,9 @@ The "activatebe" action activates the specified boot environment Create Boot Environment ======================= -The "create" action creates a new boot environment. Specify the name of -the boot environment as the "newbe". By default, this action clones the -active boot environment. To specify another, inactive boot environment, +The "create" action creates a new boot environment. Specify the name of +the boot environment as the "newbe". By default, this action clones the +active boot environment. To specify another, inactive boot environment, also include "clonefrom" to specify which boot environment to clone from. **REST Request** @@ -247,7 +245,7 @@ also include "clonefrom" to specify which boot environment to clone from. "name": "response", "namespace": "sysadm" } - + .. index:: destroybe, beadm .. _Destroy a Boot Environment: @@ -255,10 +253,9 @@ also include "clonefrom" to specify which boot environment to clone from. Destroy a Boot Environment ========================== -The "destroybe" action destroys the specified "target" boot environment +The "destroybe" action destroys the specified "target" boot environment and forcefully unmounts it. - **REST Request** :: @@ -297,7 +294,7 @@ and forcefully unmounts it. "name": "response", "namespace": "sysadm" } - + .. index:: mountbe, beadm .. _Mount a Boot Environment: @@ -305,7 +302,7 @@ and forcefully unmounts it. Mount a Boot Environment ======================== -The "mountbe" action mounts the specified boot environment. Use the +The "mountbe" action mounts the specified boot environment. Use the optional "mountpoint" argument to specify the mount point. **REST Request** @@ -349,7 +346,7 @@ optional "mountpoint" argument to specify the mount point. "name": "response", "namespace": "sysadm" } - + .. index:: umountbe, beadm .. _Unmount a Boot Environment: @@ -357,7 +354,7 @@ optional "mountpoint" argument to specify the mount point. Unmount a Boot Environment ========================== -The "umountbe" action forcibly unmounts the specified boot environment, +The "umountbe" action forcibly unmounts the specified boot environment, even if it is in use. **REST Request** diff --git a/docs/api_reference/classes/dispatcher.rst b/docs/api_reference/classes/dispatcher.rst index 956b6fd..6afb3b8 100644 --- a/docs/api_reference/classes/dispatcher.rst +++ b/docs/api_reference/classes/dispatcher.rst @@ -3,30 +3,30 @@ dispatcher ********** -The dispatcher class is used to spin up external processes on demand, +The dispatcher class is used to spin up external processes on demand, such as a user running a custom system setup script. -Every dispatcher class request contains the following parameters: +Every dispatcher class request contains several parameters: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | dispatcher | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | rpc | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| action | | supported actions include "list", "kill" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------+------------+--------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+============+======================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+------------+--------------------------------------+ +| name | dispatcher | | +| | | | ++---------------+------------+--------------------------------------+ +| namespace | rpc | | +| | | | ++---------------+------------+--------------------------------------+ +| action | | Actions include "list" and "kill". | +| | | | ++---------------+------------+--------------------------------------+ -The rest of this section provides examples of the available *actions* -for each type of request, along with their responses. +The rest of this section provides examples of the available *actions* +for each type of request, along with their responses. .. index:: list, dispatcher @@ -35,8 +35,8 @@ for each type of request, along with their responses. List Processes ============== -The "list" action lists all the currently running or pending processes -within the dispatcher queues. Possible queues are "no_queue", +The "list" action lists all the currently running or pending processes +within the dispatcher queues. Possible queues are "no_queue", "pkg_queue", and "iocage_queue". **REST Request** @@ -83,7 +83,7 @@ within the dispatcher queues. Possible queues are "no_queue", "name": "response", "namespace": "rpc" } - + .. index:: kill, dispatcher .. _Kill Processes: @@ -91,7 +91,7 @@ within the dispatcher queues. Possible queues are "no_queue", Kill Processes ============== -The "kill" action allows a user with full access to cancel pending or +The "kill" action allows a user with full access to cancel pending or running jobs within the dispatcher system. **REST Request** diff --git a/docs/api_reference/classes/fs.rst b/docs/api_reference/classes/fs.rst index c76f6b0..943ae66 100644 --- a/docs/api_reference/classes/fs.rst +++ b/docs/api_reference/classes/fs.rst @@ -5,27 +5,27 @@ fs The fs class is used to manage the files and directories on the system. -Every fs class request contains the following parameters: +Every fs class request contains several parameters: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | fs | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| action | | supported actions include "dirlist" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------+-----------+--------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+======================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-----------+--------------------------------------+ +| name | fs | | +| | | | ++---------------+-----------+--------------------------------------+ +| namespace | sysadm | | +| | | | ++---------------+-----------+--------------------------------------+ +| action | | Actions include "dirlist". | +| | | | ++---------------+-----------+--------------------------------------+ -The rest of this section provides examples of the available *actions* -for each type of request, along with their responses. +The rest of this section provides examples of the available *actions* +for each type of request, along with their responses. .. index:: dirlist, fs diff --git a/docs/api_reference/classes/iocage.rst b/docs/api_reference/classes/iocage.rst index 4fc47fb..6535034 100644 --- a/docs/api_reference/classes/iocage.rst +++ b/docs/api_reference/classes/iocage.rst @@ -3,33 +3,35 @@ iocage ****** -The iocage class is used to manage jails which provide a light-weight, -operating system-level virtualization for running applications or +The iocage class is used to manage jails, which provide a light-weight, +operating system-level virtualization for running applications or services. Every iocage class request contains the following parameters: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | iocage | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| action | | supported actions include "getdefaultsettings", "listjails", "getjailsettings", "df", "startjail", "stopjail", | -| | | "capjail", "clonejail", "createjail", "destroyjail", "execjail", "cleanjails", "cleanreleases", "cleantemplates", | -| | | "cleanall", "activatepool", and "deactivatepool" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------+-----------+------------------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+======================================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-----------+------------------------------------------------------+ +| name | iocage | | +| | | | ++---------------+-----------+------------------------------------------------------+ +| namespace | sysadm | | +| | | | ++---------------+-----------+------------------------------------------------------+ +| action | | Actions include "activatepool", "capjail", | +| | | "cleanall", "cleanjails", "cleanreleases", | +| | | "cleantemplates", "clonejail", "createjail", | +| | | "deactivatepool", "destroyjail", "df", | +| | | "execjail", "getdefaultsettings", "getjailsettings", | +| | | "listjails", "startjail", and "stopjail". | ++---------------+-----------+------------------------------------------------------+ -The rest of this section provides examples of the available *actions* -for each type of request, along with their responses. +The rest of this section provides examples of the available *actions* +for each type of request, along with their responses. .. index:: getdefaultsettings, iocage @@ -38,7 +40,7 @@ for each type of request, along with their responses. Default Settings ================ -The "getdefaultsettings" action lists all of the global settings that +The "getdefaultsettings" action lists all of the global settings that apply to all jails. **REST Request** @@ -318,10 +320,10 @@ List Jails ========== The "listjails" action lists information about currently installed jails. -For each jail, the response includes the UUID of the jail, whether or -not the jail has been configured to start at system boot, the jail ID -(only applies to running jails), whether or not the jail is running, a -friendly name for the jail (tag), and the type of jail (basejail or +For each jail, the response includes the UUID of the jail, whether or +not the jail has been configured to start at system boot, the jail ID +(only applies to running jails), whether or not the jail is running, a +friendly name for the jail (tag), and the type of jail (basejail or thickjail). **REST Request** @@ -394,16 +396,16 @@ thickjail). Jail Settings ============= -The "getjailsettings" action lists settings that apply to the specified +The "getjailsettings" action lists settings that apply to the specified jail. This action supports 4 modes: -* specify a property and a jail +* Specify a property and a jail. -* specify a property and *-r* for all downloaded releases +* Specify a property and *-r* for all downloaded releases. -* specify *all* properties for the specified jail +* Specify *all* properties for the specified jail. -* specify the jail +* Specify the jail. Here is an example of specifying the property and the jail: @@ -659,7 +661,7 @@ jail, as both modes produce identical outputs: "name": "response", "namespace": "sysadm" } - + .. index:: df, iocage .. _List Resource Usage: @@ -667,9 +669,9 @@ jail, as both modes produce identical outputs: List Resource Usage =================== -The "df" action lists resource usage for all jails. For each jail, the -response includes: CRT (compression ratio), RES (reserved space), QTA -(disk quota), USE (used space), AVA (available space), and TAG (jail +The "df" action lists resource usage for all jails. For each jail, the +response includes: CRT (compression ratio), RES (reserved space), QTA +(disk quota), USE (used space), AVA (available space), and TAG (jail name). **REST Request** @@ -723,7 +725,7 @@ name). "name": "response", "namespace": "sysadm" } - + .. index:: startjail, iocage .. _Start a Jail: @@ -733,7 +735,7 @@ Start a Jail The "startjail" action starts the specified jail. -.. note:: A jail can be started only once. If the jail is already +.. warning:: A jail can be started only once. If the jail is already running, an error message will be generated. **REST Request** @@ -792,7 +794,7 @@ The "startjail" action starts the specified jail. "name": "response", "namespace": "sysadm" } - + .. index:: stopjail, iocage .. _Stop a Jail: @@ -802,7 +804,7 @@ Stop a Jail The "stopjail" action stops the specified jail. -.. note:: A jail can be only stopped once. If the jail has already +.. warning:: A jail can be only stopped once. If the jail has already stopped, an error message will be generated. **REST Request** @@ -863,7 +865,7 @@ The "stopjail" action stops the specified jail. "name": "response", "namespace": "sysadm" } - + .. index:: capjail, iocage .. _Cap a Jail: @@ -871,7 +873,7 @@ The "stopjail" action stops the specified jail. Cap a Jail =========== -The "capjail" action re-applies resource limits to a running jail. Use +The "capjail" action re-applies resource limits to a running jail. Use this action when you make a change to the specified jail's resources and want to apply the changes without restarting the jail. @@ -913,7 +915,7 @@ want to apply the changes without restarting the jail. "name": "response", "namespace": "sysadm" } - + .. index:: clonejail, iocage .. _Clone a Jail: @@ -921,13 +923,13 @@ want to apply the changes without restarting the jail. Clone a Jail ============ -The "clonejail" action clones the specified "jail". By default, the -clone will inherit that jail's properties. Use "props" to specify any +The "clonejail" action clones the specified "jail". By default, the +clone will inherit that jail's properties. Use "props" to specify any properties that should differ. All available properties are described in -`iocage(8) `_. +`iocage(8) `_. -In this example, the "tag" property is specified so that the new jail -has a different name than the jail it was cloned from. +In this example, the "tag" property is specified so that the new jail +has a different name than the jail it was cloned from. **REST Request** @@ -973,7 +975,7 @@ has a different name than the jail it was cloned from. "name": "response", "namespace": "sysadm" } - + In this example, no properties are specified so iocage populates its own values and the props returned in the response is empty: @@ -1019,7 +1021,7 @@ values and the props returned in the response is empty: "name": "response", "namespace": "sysadm" } - + .. index:: createjail, iocage .. _Create a Jail: @@ -1027,11 +1029,13 @@ values and the props returned in the response is empty: Create a Jail ============= -The "createjail" action creates a jail. +The "createjail" action creates a jail. -In this example, the "tag" property sets the name of the new jail and +In this example, the "tag" property sets the name of the new jail and the "release" property specifies which template to use. +.. TODO CONTINUE EDITING BELOW------------------------------------------ + **REST Request** :: 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..ec73b35 100644 --- a/docs/api_reference/connection.rst +++ b/docs/api_reference/connection.rst @@ -4,24 +4,24 @@ Getting Started *************** Welcome to the SysAdm™ API (application programming interface) -documentation handbook! SysAdm™ is a complex utility with many integral -subsystems and classes, and this handbook will attempt to guide a new -user through the initialization, core features, and intricacies of the -utility. +Reference Guide! SysAdm™ is a complex utility with many integral +subsystems and classes, and this reference guide will attempt to +accurately represent the initialization, core features, and intricacies +of the utility. -This handbook will be heavily utilizing the Websocket specification and -JSON (JavaScript Object Notation) format. For detailed descriptions of -these items, please refer to their respective websites at -http://www.websocket.org and http://json.org/. +This handbook will be heavily utilizing the Websocket specification and +JSON (JavaScript Object Notation) format. For detailed descriptions of +these items, please refer to their respective websites at +http://www.websocket.org and http://json.org/. .. _Authentication: 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 +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 following parameters: +----------------+------------+---------------------------------------+ @@ -43,17 +43,17 @@ following parameters: +----------------+------------+---------------------------------------+ There are three options for server authentication: username and password, -token authentication, and pre-registered SSL certifications. SSL -certification requests are handled by both server and bridge, while +token authentication, and pre-registered SSL certifications. SSL +certification requests are handled by both server and bridge, while token authentication and username/password requests are server side only. -.. note:: individual servers can be configured to refuse username and +.. tip:: Individual servers can be configured to refuse username and password requests altogether. **1. Username and Password:** **WebSocket Request: (Server only)** - + .. code-block:: json { @@ -66,13 +66,13 @@ token authentication and username/password requests are server side only. } } -.. note:: when connecting to the localhost, the password field may be +.. tip:: When connecting to the localhost, the password field may be left empty for non-root user access. **2. Token Authentication: (Server only)** **WebSocket Request** - + .. code-block:: json { @@ -84,15 +84,15 @@ token authentication and username/password requests are server side only. } } -Here is an example of using a pre-registered SSL certificate to request -authentication. Note that this is a two-step process with only a 30 -seconds window of validity, so this is best left to automated systems +Here is an example of using a pre-registered SSL certificate to request +authentication. Note that this is a two-step process with only a 30 +seconds window of validity, so this is best left to automated systems rather than direct user requests. **3.1. SSL Certificate Authentication: (Server and Bridge)** **WebSocket Request (Stage 1 - Initial Request)** - + .. code-block:: json { @@ -115,11 +115,11 @@ rather than direct user requests. "namespace": "rpc" } -On receipt of the "test_string", the user-side client must encrypt that -string with the desired SSL certificate/key combination, then return -that encrypted string back to the server (Stage 2) within 30 seconds of -the initial stage 1 reply. The encrypted string should also be -base64-encoded before insertion into the stage 2 JSON request to ensure +On receipt of the "test_string", the user-side client must encrypt that +string with the desired SSL certificate/key combination, then return +that encrypted string back to the server (Stage 2) within 30 seconds of +the initial stage 1 reply. The encrypted string should also be +base64-encoded before insertion into the stage 2 JSON request to ensure accurate transport back to the server. **WebSocket Request (Stage 2 - Return Encoded String)** @@ -135,7 +135,7 @@ accurate transport back to the server. } } -A successful authentication will provide a reply similar to this: +A successful authentication will provide a similar reply: **WebSocket Reply** @@ -151,17 +151,17 @@ A successful authentication will provide a reply similar to this: "namespace": "rpc" } -.. note:: the first element of the "args" array is the authentication - token for use later as necessary, while the second element is - the number of seconds for which that token is valid. The token - is reset after every successful communication with the - websocket. In this example, it is set to 5 minutes of - inactivity before the token is invalidated. The websocket - server is currently set to close any connection to a client +.. note:: The first element of the "args" array is the authentication + token for later use, while the second element is + the number of seconds the token will remain valid. The token + is reset after every successful communication with the + websocket. In this example, it is set to 5 minutes of + inactivity before the token is invalidated. The websocket + server is currently set to close any connection to a client after 10 minutes of inactivity. -An invalid authentication, or a system request after the user session -has timed out due to inactivity, looks like this: +An invalid authentication or a system request after the user session +has timed out due to inactivity will have a specific message: **WebSocket Reply** @@ -177,8 +177,7 @@ has timed out due to inactivity, looks like this: "namespace": "rpc" } -To clear a pre-saved authentication token, such as signing out, use this -request: +To clear a pre-saved authentication token, such as signing out: **WebSocket Request** @@ -196,11 +195,11 @@ request: **3.2. Alternate SSL Certificate Authentication Initiation (server through bridge)** -This is an alternate method for stage 1 of the SSL Certificate -Authentication method. In this case, the initial request has specified -using a base 64 encoded key, to which the server will respond with its -own encrypted message. This prevents the bridge from being able to -decrypt messages between client and server for the duration of the +This is an alternate method for stage 1 of the SSL Certificate +Authentication method. In this case, the initial request has specified +using a base 64 encoded key, to which the server will respond with its +own encrypted message. This prevents the bridge from being able to +decrypt messages between client and server for the duration of the connection. **WebSocket Request (Stage 1 - Initial Request)** @@ -233,16 +232,15 @@ connection. } -.. important:: in the above reply, both values for "test_string" and - "new_ssl_key" are encrypted with the public SSL key - matching the md5 sum from the initial request and then - base 64 encoded for transport. All future messages are - bulk encrypted with the "new_ssl_key", which is a new - randomly generated private key only known to the server - and client. For example, the following section {"id", - "name","namespace","args"} will now be encrypted with the - private key in one block prior to transport through the - bridge. +.. danger:: In the reply above, both values for "test_string" and + "new_ssl_key" are encrypted with the public SSL key matching + the md5 sum from the initial request and then base 64 + encoded for transport. All future messages are bulk + encrypted with the "new_ssl_key", which is a new randomly + generated private key only known to the server and client. + For example, the following section {"id", "name", + "namespace","args"} will now be encrypted with the private + key in one block prior to transport through the bridge. .. _SSL Certificate Management: @@ -252,25 +250,25 @@ SSL Certificate Management Several actions are available for managing the SSL certificates used for authentication. -+---------------------------------+---------------+----------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+========================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------+ -| name | settings | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------+ -| namespace | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------+ -| action | | supported actions include "list_ssl_certs", "register_ssl_cert", and "revoke_ssl_cert" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------+ ++---------------+-----------+---------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+=============================================+ +| id | | Any unique value for the request; examples | +| | | include a hash, checksum, or uuid. | ++---------------+-----------+---------------------------------------------+ +| name | settings | | +| | | | ++---------------+-----------+---------------------------------------------+ +| namespace | sysadm | | +| | | | ++---------------+-----------+---------------------------------------------+ +| action | | Actions include "list_ssl_certs", | +| | | "register_ssl_cert", and "revoke_ssl_cert". | ++---------------+-----------+---------------------------------------------+ -The rest of this section provides examples of the available *actions* -for each type of request, along with their responses. +The rest of this section provides examples of the available *actions* +for each type of request, along with their responses. .. index:: list_ssl_certs, settings @@ -279,15 +277,15 @@ for each type of request, along with their responses. List SSL Certificates --------------------- -The "list_ssl_certificates" action lists the known and registered -certificates. For each certificate, the response includes the username, +The "list_ssl_certificates" action lists the known and registered +certificates. For each certificate, the response includes the username, public key, and the certificate's details. **Websocket Request** .. code-block:: json - - { + + { "id" : "example_id", "name" : "settings", "namespace": "sysadm", @@ -299,8 +297,8 @@ public key, and the certificate's details. **Websocket Response** .. code-block:: json - - { + + { "id" : "example_id", "name" : "response", "namespace": "sysadm", @@ -310,8 +308,8 @@ public key, and the certificate's details. } } } - -.. note:: the "" value is base64 encoded. + +.. note:: The "" value is base64 encoded. .. index:: register_ssl_cert, settings @@ -320,17 +318,17 @@ public key, and the certificate's details. Register a SSL Certificate -------------------------- -The "register_ssl_certificate" action registers the specified -certificate on the server. Once registered, that user is allowed to -authenticate without a password as long as that same certificate is -loaded in any future connections. When using this action, The "pub_key" -needs to match the public key of one of the certificates currently +The "register_ssl_certificate" action registers the specified +certificate on the server. Once registered, a user is allowed to +authenticate without a password as long as that same certificate is +loaded in any future connections. When using this action, The "pub_key" +needs to match the public key of one of the certificates currently loaded into the server/client connection. **Websocket Request** .. code-block:: json - + { "id" : "example_id", "name" : "settings", @@ -342,21 +340,20 @@ loaded into the server/client connection. "email" : "" } } - + **Websocket Response** .. code-block:: json - - { + + { "id" : "example_id", "name" : "response", "namespace": "sysadm", "args" : {} } - -.. note:: the "nickname" and "email" arguments are optional and may not - be seen in all responses +.. note:: The "nickname" and "email" arguments are optional, and may not + be seen in all responses. .. index:: revoke_ssl_cert, settings @@ -365,18 +362,18 @@ loaded into the server/client connection. Revoke a SSL Certificate ------------------------ -The "revoke_ssl_certificate" action revokes a currently registered -certificate so that it can no longer be used for authentication. The -"pub_key" must be specified and must match one of the keys given by the +The "revoke_ssl_certificate" action revokes a currently registered +certificate so that it can no longer be used for authentication. The +"pub_key" must be specified and must match one of the keys given by the "list_ssl_certs" action, but does not need to match any currently loaded -certificates. The "user" is optional and allows a connection with full -administrative privileges to revoke a certificate belonging to another +certificates. The "user" is optional and allows a connection with full +administrative privileges to revoke a certificate belonging to another user. **Websocket Request** .. code-block:: json - + { "id" : "example_id", "name" : "settings", @@ -387,65 +384,65 @@ user. "user" : "" } } - + **Websocket Response** .. code-block:: json - - { + + { "id" : "example_id", "name" : "response", "namespace": "sysadm", "args" : {} } -.. note:: if the current user has full administrative access, - "list_ssl_certs" will return the registered certificates for +.. note:: If the current user has full administrative access, + "list_ssl_certs" will return the registered certificates for all users on the system. Otherwise, it will only return the - certificates for the current user. Similarly, - "revoke_ssl_cert" may be used to remove certificates - registered to other users only if the current user/connection + certificates for the current user. Similarly, + "revoke_ssl_cert" may be used to remove certificates + registered to other users only if the current user/connection has full administrative access; otherwise, it may only be used to manage the current user's certificates. - -.. index:: dispatcher, events + +.. index:: dispatcher, events .. _Dispatcher Subsystem: Dispatcher Subsystem ==================== -The dispatcher subsystem is designed for running external utilities or -scripts in an asynchronous fashion. Any connected client can subscribe +The dispatcher subsystem is designed for running external utilities or +scripts in an asynchronous fashion. Any connected client can subscribe to per-connection event notifications about dispatcher processes through -the events system, but only users in the *wheel* group have the -authority to directly submit new jobs for the dispatcher. +the events system, but only users in the *wheel* group have the +authority to directly submit new jobs for the dispatcher. -.. note:: other subsystems may also use the dispatcher for long-running - processes in the background, and these subsystems may allow - non-wheel group users to perform these tasks as necessary. - Also, the events namespace does not really translate over to - REST which was not designed for asyncronous events. For this +.. note:: Other subsystems may also use the dispatcher for long-running + processes in the background, and these subsystems may allow + non-wheel group users to perform these tasks as necessary. + Also, the events namespace does not really translate over to + REST which was not designed for asyncronous events. For this reason, only Websocket examples are used in this section. The format of "dispatcher" event requests is as follows: -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+==============================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| name | subscribe | use the desired action | -| | unsubscribe | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| namespace | events | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| args | dispatcher | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ ++---------------+-------------+--------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+=============+======================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-------------+--------------------------------------+ +| name | subscribe | use the desired action | +| | unsubscribe | | ++---------------+-------------+--------------------------------------+ +| namespace | events | | +| | | | ++---------------+-------------+--------------------------------------+ +| args | dispatcher | | +| | | | ++---------------+-------------+--------------------------------------+ For example, to subscribe to dispatcher events: @@ -458,11 +455,11 @@ For example, to subscribe to dispatcher events: "args" : ["dispatcher"] } -Once subscribed, the requested events will be received as they are -produced. To unsubscribe from event notifications, repeat the request, -using "unsubscribe" for the "name". For example, to unsubscribe from +Once subscribed, the requested events will be received as they are +produced. To unsubscribe from event notifications, repeat the request, +using "unsubscribe" for the "name". For example, to unsubscribe from dispatcher events: - + .. code-block:: json { @@ -486,30 +483,30 @@ This response indicates that a dispatcher event occurred: } } -A "dispatcher" query contains the following parameters: +A "dispatcher" query contains several parameters: -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+==============================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| name | dispatcher | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| namespace | events | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| action | | "run" is used to submit process commands | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ ++---------------+------------+--------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+============+======================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+------------+--------------------------------------+ +| name | dispatcher | | +| | | | ++---------------+------------+--------------------------------------+ +| namespace | events | | +| | | | ++---------------+------------+--------------------------------------+ +| action | | "run" submits process commands | +| | | | ++---------------+------------+--------------------------------------+ Dispatcher events have the following syntax: **Websocket Request** -.. code-block:: json +.. code-block:: json { "namespace" : "events", @@ -525,14 +522,16 @@ Dispatcher events have the following syntax: } } -Any user within the *wheel* group can use the "run" action to submit a +Any user within the *wheel* group can use the "run" action to submit a new job to the dispatcher: **REST Request** - - :cmd: PUT /rpc/dispatcher - -.. code-block:: json + +.. code-block:: none + + PUT /rpc/dispatcher + +.. code-block:: json { "action" : "run", @@ -545,7 +544,7 @@ new job to the dispatcher: **REST Response** -.. code-block:: json +.. code-block:: json { "args": { @@ -558,7 +557,7 @@ new job to the dispatcher: **WebSocket Request** -.. code-block:: json +.. code-block:: json { "name" : "dispatcher", @@ -576,7 +575,7 @@ new job to the dispatcher: **WebSocket Response** -.. code-block:: json +.. code-block:: json { "args": { @@ -589,52 +588,52 @@ new job to the dispatcher: "name": "response", "namespace": "rpc" } - -When submitting a job to the dispatcher, keep the following points in -mind: -* Process commands are not the same as shell commands. A dispatcher +When submitting a job to the dispatcher, there are several points to +remember: + +* Process commands are not the same as shell commands. A dispatcher process command uses the syntax " ", - similar to a simple shell command. However, complex shell operations - with pipes or test statements will not function properly within a + similar to a simple shell command. However, complex shell operations + with pipes or test statements will not function properly within a dispatcher process. * There are two types of jobs: a single string entry for simple commands, - and an array of strings for a chain of commands. A chain of commands - is treated as a single process, and the commands are run sequentially - until either a command fails (returns non-0 or the process crashes), + and an array of strings for a chain of commands. A chain of commands + is treated as a single process, and the commands are run sequentially + until either a command fails (returns non-0 or the process crashes), or until there are no more commands to run. -* A chain of commands is useful for multi-step operations but is not +* A chain of commands is useful for multi-step operations but is not considered a replacement for a good shell script on the server. - + .. _Server Subsystems: 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: -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+==============================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| name | | supported names are "query", "identify", and "list_ssl_checksums" | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| namespace | rpc | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| args | | can be any data | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ ++---------------+-----------+------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+==========================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-----------+------------------------------------------+ +| name | | Supported names are "query", "identify", | +| | | and "list_ssl_checksums" | ++---------------+-----------+------------------------------------------+ +| namespace | rpc | | +| | | | ++---------------+-----------+------------------------------------------+ +| args | | Can be any data. | +| | | | ++---------------+-----------+------------------------------------------+ -The rest of this section provides examples of the available *names* for -each type of request, along with their responses. +The rest of this section provides examples of the available *names* for +each type of request, along with their responses. .. index:: query, rpc @@ -643,8 +642,8 @@ each type of request, along with their responses. Query Subsystems ---------------- -An RPC query can be issued to probe all the known subsystems and return -which ones are currently available and what level of read and write +An RPC query can be issued to probe all the known subsystems and return +which ones are currently available and what level of read and write access the user has. This subsystem is used only by the server. **REST Request** @@ -704,9 +703,9 @@ 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 -identities are "server", "bridge", and "client," with all three system + +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. **REST Request** @@ -740,7 +739,7 @@ types using this subsystem. "name": "response", "namespace": "rpc" } - + .. index:: list_ssl_checksums, rpc .. _List SSL Checksums: @@ -748,8 +747,8 @@ types using this subsystem. List SSL Checksums ------------------ -Used by both server and client, :command:`list_ssl_checksums` will list -the MD5 checksums of all known SSL keys. +Used by both server and client, :command:`list_ssl_checksums` will list +the MD5 checksums of all known SSL keys. **REST Request** @@ -786,4 +785,4 @@ the MD5 checksums of all known SSL keys. "id": "fooid", "name": "response", "namespace": "rpc" - } + } \ No newline at end of file diff --git a/docs/api_reference/events.rst b/docs/api_reference/events.rst index 5a01182..45b3768 100644 --- a/docs/api_reference/events.rst +++ b/docs/api_reference/events.rst @@ -3,37 +3,36 @@ Events ====== -The "events" namespace can be used to setup and receive asynchronous +The "events" namespace can be used to setup and receive asynchronous updates about system status and other types of system notifications. -.. note:: The events namespace does not really translate over to REST - which was not designed for asynchronous events. For this - reason, only Websocket examples are used in this section. +.. warning:: The events namespace does not really translate over to REST + which was not designed for asynchronous events. For this + reason, only Websocket examples are used in this section. -Every events request contains the following parameters: +Every events request contains several parameters: -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+==============================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| name | | supported values are "subscribe" or unsubscribe" | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| namespace | events | | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ -| args | | values vary by type of class | -| | | | -+---------------------------------+---------------+------------------------------------------------------------------------------+ ++---------------+-----------+--------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++===============+===========+======================================+ +| id | | Any unique value for the request, | +| | | including a hash, checksum, or uuid. | ++---------------+-----------+--------------------------------------+ +| name | | Supported values are "subscribe" or | +| | | "unsubscribe". | ++---------------+-----------+--------------------------------------+ +| namespace | events | | +| | | | ++---------------+-----------+--------------------------------------+ +| args | | Values vary by type of class. | +| | | | ++---------------+-----------+--------------------------------------+ - -Subsystems can also be tracked using the events namespace. Currently, -there are three trackable subsystems: Dispatcher, Life Preserver, and -System State. The following is a template to subscribe to various -subsystem event notifications: +Subsystems can also be tracked using the events namespace. Currently, +there are three trackable subsystems: Dispatcher, Life Preserver, and +System State. Use the template to subscribe to various subsystem event +notifications: **Websocket Request** @@ -45,13 +44,13 @@ subsystem event notifications: "id" : "sampleID", "args" : ["dispatcher", "life-preserver", "system-state"] } - -Once subscribed, events will be received as they are produced. To + +Once subscribed, events will be received as they are produced. To unsubscribe from events, repeat the request, using "unsubscribe" for the -"name". +"name". Here is an example reply from the Life Preserver subsystem: - + **Websocket Reply** .. code-block:: json @@ -72,8 +71,8 @@ Dispatcher The Dispatcher subsystem is used by SysAdm™ to process external commands and return specific information from the utility. This is managed on the -server as a separate process, and will not interrupt primary server -tasks. To subscribe to the Dispatcher subsystem for event updates, use +server as a separate process, and will not interrupt primary server +tasks. To subscribe to the Dispatcher subsystem for event updates, use the following: **Websocket Request** @@ -145,11 +144,10 @@ reflect the differences between these states: } } - -Individual classes such as iohyve will move these dispatcher elements -into a "process_details" section. Tailored sample responses will be -provided in these classes' individual documentation pages. A generalized -sample is as follows: +Individual classes such as iohyve will move these dispatcher elements +into a "process_details" section. Tailored sample responses will be +provided in these classes' individual documentation pages. Here is a +generalized sample: **Dispatcher Class Event Message** @@ -167,13 +165,13 @@ sample is as follows: } } -For specific details on these special types of events please refer to +For specific details on these special types of events please refer to the Classes section of this User Guide. Life Preserver -------------- -To subscribe to the Life Preserver subsystem for event updates, use the +To subscribe to the Life Preserver subsystem for event updates, use the following: **Websocket Request** @@ -201,12 +199,11 @@ following: "class" : "snapshot/replication" } } - System State ------------ -To subscribe to the System State subsystem for event updates, use the +To subscribe to the System State subsystem for event updates, use the following: **Websocket Request** @@ -250,14 +247,14 @@ error has occurred. } } } - + Bridge ------ -Bridge events are automatically received by any system connected to a -bridge, with no subscription required. This event will get sent out any -time a new connection/disconnection is made from the bridge which -impacts the current connection. A client will only get the event when a +Bridge events are automatically received by any system connected to a +bridge, with no subscription required. This event will get sent out any +time a new connection/disconnection is made from the bridge which +impacts the current connection. A client will only get the event when a server connects/disconnects or vice versa. **Websocket Reply: Connected Bridge** @@ -273,6 +270,7 @@ server connects/disconnects or vice versa. } } -.. note:: Available_connections are **all** the connections available at - the time, **not** a difference from a previous state. There may be - both new ID's in the list and ID's which are no longer listed. \ No newline at end of file +.. tip:: Available_connections are **all** the connections available at + the time, **not** a difference from a previous state. There may + be both new ID's in the list and ID's which are no longer + listed. \ No newline at end of file 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*/