From 4bf475bdc61cad337372093ed1d53944bd1fc2ee Mon Sep 17 00:00:00 2001 From: Mrt134 Date: Tue, 5 Jul 2016 18:26:39 -0400 Subject: [PATCH] SysAdm PEP8 Conversion - Converted SysAdm Server Handbook to PEP8 standards. - Converted SysAdm API Handbook to PEP8 standards. --- api/classes/beadm.rst | 31 ++- api/classes/dispatcher.rst | 15 +- api/classes/fs.rst | 3 +- api/classes/iocage.rst | 91 ++++++--- api/classes/iohyve.rst | 50 +++-- api/classes/lifepreserver.rst | 78 +++++--- api/classes/logs.rst | 31 ++- api/classes/network.rst | 14 +- api/classes/pkg.rst | 105 ++++++---- api/classes/systemmanager.rst | 45 +++-- api/classes/updates.rst | 32 +++- api/classes/zfs.rst | 46 +++-- api/connection.rst | 351 +++++++++++++++++++++------------- api/events.rst | 92 +++++---- docs/basics.rst | 79 ++++++-- docs/introduction.rst | 24 ++- docs/manage.rst | 20 +- 17 files changed, 731 insertions(+), 376 deletions(-) diff --git a/api/classes/beadm.rst b/api/classes/beadm.rst index 5bd0412..b4d1560 100644 --- a/api/classes/beadm.rst +++ b/api/classes/beadm.rst @@ -24,7 +24,8 @@ Every beadm class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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 @@ -33,8 +34,10 @@ The rest of this section provides examples of the available *actions* for each t 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" is active on reboot, "N" is active now and -"-" is inactive), the date it was created, its mount point, its nickname, and its size. +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** @@ -94,7 +97,9 @@ The "listbes" action retrieves the list of boot environments. For each boot envi 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 environment as the "target". +The "renamebe" action renames the specified boot environment. When using +this action, specify the new name as the "source" and the boot +environment as the "target". **REST Request** @@ -146,7 +151,8 @@ The "renamebe" action renames the specified boot environment. When using this ac Activate Boot Environment ========================= -The "activatebe" action activates the specified boot environment (target) so that it will be the default at next boot. +The "activatebe" action activates the specified boot environment +(target) so that it will be the default at next boot. **REST Request** @@ -195,8 +201,10 @@ The "activatebe" action activates the specified boot environment (target) so tha 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, also include "clonefrom" to specify which boot environment to clone from. +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 +255,8 @@ To specify another, inactive boot environment, also include "clonefrom" to speci Destroy a Boot Environment ========================== -The "destroybe" action destroys the specified "target" boot environment and forcefully unmounts it. +The "destroybe" action destroys the specified "target" boot environment +and forcefully unmounts it. **REST Request** @@ -296,7 +305,8 @@ The "destroybe" action destroys the specified "target" boot environment and forc Mount a Boot Environment ======================== -The "mountbe" action mounts the specified boot environment. Use the optional "mountpoint" argument to specify the mount point. +The "mountbe" action mounts the specified boot environment. Use the +optional "mountpoint" argument to specify the mount point. **REST Request** @@ -347,7 +357,8 @@ The "mountbe" action mounts the specified boot environment. Use the optional "mo Unmount a Boot Environment ========================== -The "umountbe" action forcibly unmounts the specified boot environment, even if it is in use. +The "umountbe" action forcibly unmounts the specified boot environment, +even if it is in use. **REST Request** diff --git a/api/classes/dispatcher.rst b/api/classes/dispatcher.rst index 82fea92..b31b404 100644 --- a/api/classes/dispatcher.rst +++ b/api/classes/dispatcher.rst @@ -3,7 +3,8 @@ dispatcher ********** -The dispatcher class is used to spin up external processes on demand, such as a user running a custom system setup script. +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: @@ -24,7 +25,8 @@ Every dispatcher class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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 @@ -33,7 +35,9 @@ The rest of this section provides examples of the available *actions* for each t List Processes ============== -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". +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** @@ -67,7 +71,7 @@ The "list" action lists all the currently running or pending processes within th "pkg_queue": { "sysadm_pkg_install-{9c079421-ace9-4b6e-8870-d023b48f4c49}": { "commands": [ - "pkg install -y --repository \"pcbsd-major\" misc/pcbsd-meta-mate" + "pkg install -y --repository \"pcbsd-major\"misc/pcbsd-meta-mate" ], "queue_position": "0", "state": "running" @@ -87,7 +91,8 @@ The "list" action lists all the currently running or pending processes within th Kill Processes ============== -The "kill" action allows a user with full access to cancel pending or running jobs within the dispatcher system. +The "kill" action allows a user with full access to cancel pending or +running jobs within the dispatcher system. **REST Request** diff --git a/api/classes/fs.rst b/api/classes/fs.rst index fb47751..a8128db 100644 --- a/api/classes/fs.rst +++ b/api/classes/fs.rst @@ -24,7 +24,8 @@ Every fs class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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/api/classes/iocage.rst b/api/classes/iocage.rst index 122f661..a65d07b 100644 --- a/api/classes/iocage.rst +++ b/api/classes/iocage.rst @@ -3,7 +3,9 @@ iocage ****** -The iocage class is used to manage jails which provide a light-weight, operating system-level virtualization for running applications or services. +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: @@ -26,7 +28,8 @@ Every iocage class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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 @@ -35,7 +38,8 @@ The rest of this section provides examples of the available *actions* for each t Default Settings ================ -The "getdefaultsettings" action lists all of the global settings that apply to all jails. +The "getdefaultsettings" action lists all of the global settings that +apply to all jails. **REST Request** @@ -313,8 +317,12 @@ The "getdefaultsettings" action lists all of the global settings that apply to a 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 thickjail). +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 +thickjail). **REST Request** @@ -386,7 +394,8 @@ system boot, the jail ID (only applies to running jails), whether or not the jai Jail Settings ============= -The "getjailsettings" action lists settings that apply to the specified jail. This action supports 4 modes: +The "getjailsettings" action lists settings that apply to the specified +jail. This action supports 4 modes: * specify a property and a jail @@ -491,7 +500,8 @@ Here is an example of using *-r* and a specifed property: "namespace": "sysadm" } -An example of specifying either *all* and a jail, or just specifying the jail, as both modes produce identical outputs: +An example of specifying either *all* and a jail, or just specifying the +jail, as both modes produce identical outputs: **REST Request** @@ -657,8 +667,10 @@ An example of specifying either *all* and a jail, or just specifying the jail, a 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 name). +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** @@ -721,7 +733,8 @@ Start a Jail The "startjail" action starts the specified jail. -.. note:: since a jail can only be started once, you will receive an error if the jail is already running. +.. note:: since a jail can only be started once, you will receive an +error if the jail is already running. **REST Request** @@ -789,7 +802,8 @@ Stop a Jail The "stopjail" action stops the specified jail. -.. note:: since a jail can only be stopped once, you will receive an error if the jail is not running. +.. note:: since a jail can only be stopped once, you will receive an +error if the jail is not running. **REST Request** @@ -857,8 +871,9 @@ The "stopjail" action stops the specified jail. Cap a Jail =========== -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. +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. **REST Request** @@ -906,10 +921,13 @@ 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 properties that should differ. All available -properties are described in `iocage(8) `_. +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) `_. -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** @@ -956,7 +974,8 @@ In this example, the "tag" property is specified so that the new jail has a diff "namespace": "sysadm" } -In this example, no properties are specified so iocage populates its own values and the props returned in the response is empty: +In this example, no properties are specified so iocage populates its own +values and the props returned in the response is empty: **REST Request** @@ -1010,7 +1029,8 @@ Create a Jail The "createjail" action creates a jail. -In this example, the "tag" property sets the name of the new jail and the "release" property specifies which template to use. +In this example, the "tag" property sets the name of the new jail and +the "release" property specifies which template to use. **REST Request** @@ -1055,8 +1075,9 @@ In this example, the "tag" property sets the name of the new jail and the "relea "namespace": "sysadm" } -In this example, the **-e** switch, which creates an empty jail, is specified using "switches". Refer to `iocage(8) `_ for the list -of available switches. +In this example, the **-e** switch, which creates an empty jail, is +specified using "switches". Refer to `iocage(8) `_ +for the list of available switches. **REST Request** @@ -1110,7 +1131,9 @@ of available switches. Destroy a Jail ============== -The "destroyjail" action destroys the specified jail. This action is irreversible and does not prompt for confirmation, but will fail if the jail is running. +The "destroyjail" action destroys the specified jail. This action is +irreversible and does not prompt for confirmation, but will fail if the +jail is running. **REST Request** @@ -1160,8 +1183,10 @@ The "destroyjail" action destroys the specified jail. This action is irreversibl Run Command =========== -The "execjail" action executes the specified "command" under the privileges of the specified "user" in the specified "jail". The response will indicate whether or not command execution -succeeded as well as any output from the command. +The "execjail" action executes the specified "command" under the +privileges of the specified "user" in the specified "jail". The response +will indicate whether or not command execution succeeded as well as any +output from the command. **REST Request** @@ -1215,7 +1240,8 @@ succeeded as well as any output from the command. Clean Jails =========== -The "cleanjails" action destroys all existing jail datasets, including all data stored in the jails. +The "cleanjails" action destroys all existing jail datasets, including +all data stored in the jails. **REST Request** @@ -1261,7 +1287,9 @@ The "cleanjails" action destroys all existing jail datasets, including all data Clean Releases ============== -The "cleanreleases" action deletes all releases that have been fetched. Since basejails rely on releases, do not run this action if any basejails still exist. +The "cleanreleases" action deletes all releases that have been fetched. +Since basejails rely on releases, do not run this action if any +basejails still exist. **REST Request** @@ -1403,7 +1431,9 @@ The "cleanall" action destroys everything associated with iocage. Activate a Pool =============== -The "activatepool" action can be used to specify which ZFS pool is used to store jails. If you do not specify the pool, the response will indicate the current setting. +The "activatepool" action can be used to specify which ZFS pool is used +to store jails. If you do not specify the pool, the response will +indicate the current setting. These examples specify the pool to use: @@ -1520,9 +1550,12 @@ These examples show responses when the pool is not specified: Deactivate a Pool ================= -Since only one pool can be active, the "deactivatepool" action can be used to deactivate a currently active pool. This should be done before using the -"activatepool" action to activate a different pool. When a pool is deactivated, no data is removed. However, you won't have access to its jails unless you move those datasets to the newly -activated pool or activate the old pool again. +Since only one pool can be active, the "deactivatepool" action can be +used to deactivate a currently active pool. This should be done before +using the "activatepool" action to activate a different pool. When a +pool is deactivated, no data is removed. However, you won't have access +to its jails unless you move those datasets to the newly activated pool +or activate the old pool again. **REST Request** diff --git a/api/classes/iohyve.rst b/api/classes/iohyve.rst index 1d983d0..033a629 100644 --- a/api/classes/iohyve.rst +++ b/api/classes/iohyve.rst @@ -3,7 +3,8 @@ iohyve ****** -The iohyve class is used to manage virtual machines (VMs) running in the bhyve type 2 hypervisor. +The iohyve class is used to manage virtual machines (VMs) running in the +bhyve type 2 hypervisor. Every iohyve class request contains the following parameters: @@ -26,7 +27,8 @@ Every iohyve class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: listvms, iohyve @@ -35,8 +37,11 @@ The rest of this section provides examples of the available *actions* for each t List VMs ======== -The "listvms" action lists information about currently installed VMs. For each VM, the response includes the VM's name, description, whether or not it is scheduled to start when the host -system boots, whether or not it is currently running, and whether or not the VM is currently loaded into memory. +The "listvms" action lists information about currently installed VMs. +For each VM, the response includes the VM's name, description, whether +or not it is scheduled to start when the host system boots, whether or +not it is currently running, and whether or not the VM is currently +loaded into memory. **REST Request** @@ -104,9 +109,9 @@ system boots, whether or not it is currently running, and whether or not the VM Fetch ISO ========= -The "fetchiso" action is used to retrieve the installation ISO. It is used with the "url" argument which contains the ISO address beginning with *http://*, -*ftp://*, or -*file://*. +The "fetchiso" action is used to retrieve the installation ISO. It is +used with the "url" argument which contains the ISO address beginning +with *http://*, *ftp://*, or *file://*. **REST Request** @@ -227,7 +232,8 @@ The "listisos" action lists all the known ISO files which iohyve can use. Rename ISO ========== -The "renameiso" action is used to to rename an existing ISO file on disk. Specify the existing name with "source" and the new name with "target". +The "renameiso" action is used to to rename an existing ISO file on disk. +Specify the existing name with "source" and the new name with "target". **REST Request** @@ -278,7 +284,8 @@ The "renameiso" action is used to to rename an existing ISO file on disk. Specif Remove ISO ========== -The "rmiso" action is used to to remove an existing ISO file from disk. Specify the ISO's name as the "target". +The "rmiso" action is used to to remove an existing ISO file from disk. +Specify the ISO's name as the "target". **REST Request** @@ -326,7 +333,9 @@ The "rmiso" action is used to to remove an existing ISO file from disk. Specify Setup iohyve ============ -The "setup" action performs the initial setup of iohyve. It is mandatory to specify the FreeBSD device name of the "nic" and the ZFS "pool" to use. +The "setup" action performs the initial setup of iohyve. It is mandatory +to specify the FreeBSD device name of the "nic" and the ZFS "pool" to +use. **REST Request** @@ -377,7 +386,8 @@ The "setup" action performs the initial setup of iohyve. It is mandatory to spec Determine iohyve Setup ====================== -The "issetup" action queries if iohyve has been setup and returns either "true" or "false". +The "issetup" action queries if iohyve has been setup and returns either +"true" or "false". **REST Request** @@ -423,7 +433,8 @@ The "issetup" action queries if iohyve has been setup and returns either "true" Create Guest ============ -The "create" action creates a new iohyve guest of the specified "name" and "size". +The "create" action creates a new iohyve guest of the specified "name" +and "size". **REST Request** @@ -474,8 +485,10 @@ The "create" action creates a new iohyve guest of the specified "name" and "size Install Guest ============= -The "install" action starts the iohyve installation of the specified guest from the specified ISO. This action only boots the VM with the ISO; to do the actual installation, -run :command:`iohyve console ` from the system. +The "install" action starts the iohyve installation of the specified +guest from the specified ISO. This action only boots the VM with the ISO; +to do the actual installation, run :command:`iohyve console ` from +the system. **REST Request** @@ -770,7 +783,9 @@ The "listdisks" action lists the disks connected to the specified VM. Resize a Disk ============= -The "resizedisk" action **increases** the specified disk in the specified VM. The new specified size must be larger than the current size. +The "resizedisk" action **increases** the specified disk in the +specified VM. The new specified size must be larger than the current +size. **REST Request** @@ -984,8 +999,9 @@ The "getprops" action lists the properties for the specified guest. Set Guest Properties ===================== -The "setprop" action can be used to modify the properties for the specified guest. For each property, specify its name and desired value. Use "getprops" to see the current properties -and values for the guest. +The "setprop" action can be used to modify the properties for the +specified guest. For each property, specify its name and desired value. +Use "getprops" to see the current properties and values for the guest. **REST Request** diff --git a/api/classes/lifepreserver.rst b/api/classes/lifepreserver.rst index a72a648..8eded40 100644 --- a/api/classes/lifepreserver.rst +++ b/api/classes/lifepreserver.rst @@ -3,7 +3,8 @@ lifepreserver ************* -The lifepreserver class is used to manage and retrieve information about scheduled snapshots and replication. +The lifepreserver class is used to manage and retrieve information about +scheduled snapshots and replication. Every lifepreserver class request contains the following parameters: @@ -26,7 +27,8 @@ Every lifepreserver class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: listcron, Life Preserver @@ -35,8 +37,11 @@ The rest of this section provides examples of the available *actions* for each t List Schedules ============== -The "listcron" action retrieves the information for each Life Preserver scheduled task. If snapshots have been configured for a ZFS pool, it lists the number of snapshots to keep and -the time that snapshots are taken. If scrubs have been configured on that ZFS pool, it also lists the time that ZFS scrubs occur. +The "listcron" action retrieves the information for each Life Preserver +scheduled task. If snapshots have been configured for a ZFS pool, it +lists the number of snapshots to keep and the time that snapshots are +taken. If scrubs have been configured on that ZFS pool, it also lists +the time that ZFS scrubs occur. **REST Request** @@ -103,7 +108,8 @@ the time that snapshots are taken. If scrubs have been configured on that ZFS po Create a Snapshot Schedule ========================== -The "cronsnap" action is used to create snapshot schedules for Life Preserver. This action supports the following parameters: +The "cronsnap" action is used to create snapshot schedules for Life +Preserver. This action supports the following parameters: +---------------------------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Description** | @@ -187,7 +193,8 @@ The "cronsnap" action is used to create snapshot schedules for Life Preserver. T Create a Scrub Schedule ========================== -The "cronscrub" action is used to schedule a ZFS scrub. This action supports the following parameters: +The "cronscrub" action is used to schedule a ZFS scrub. This action +supports the following parameters: +---------------------------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Description** | @@ -264,7 +271,8 @@ The "cronscrub" action is used to schedule a ZFS scrub. This action supports the Create a Snapshot ================= -The "createsnap" action creates a one-time snapshot of the specified dataset. +The "createsnap" action creates a one-time snapshot of the specified +dataset. **REST Request** @@ -400,10 +408,14 @@ The "listsnap" action retrieves the list of saved snapshots. Revert a Snapshot ================= -The "revertsnap" action is used to rollback the contents of the specified dataset to the point in time that the specified snapshot was taken. +The "revertsnap" action is used to rollback the contents of the +specified dataset to the point in time that the specified snapshot was +taken. -.. warning:: performing this operation will revert the contents of the dataset back in time, meaning that all changes to the dataset's files that occurred since the snapshot was taken will - be lost. +.. warning:: performing this operation will revert the contents of the + dataset back in time, meaning that all changes to the + dataset's files that occurred since the snapshot was taken + will be lost. **REST Request** @@ -467,7 +479,8 @@ The "revertsnap" action is used to rollback the contents of the specified datase Remove a Snapshot ================= -The "removesnap" action is used to remove a ZFS snapshot from the specified dataset or pool. +The "removesnap" action is used to remove a ZFS snapshot from the +specified dataset or pool. **REST Request** @@ -531,7 +544,8 @@ The "removesnap" action is used to remove a ZFS snapshot from the specified data Add Replication =============== -The "addreplication" action is used to create a replication task in Life Preserver. This action supports the following parameters: +The "addreplication" action is used to create a replication task in Life +Preserver. This action supports the following parameters: +---------------------------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Description** | @@ -641,8 +655,9 @@ The "addreplication" action is used to create a replication task in Life Preserv Remove Replication ================== -The "removereplication" action is used to delete an existing replication task. Note that this action only deletes the task--it does not remove any already replicated data from the -remote system. +The "removereplication" action is used to delete an existing replication +task. Note that this action only deletes the task--it does not remove +any already replicated data from the remote system. This action supports the following parameters: @@ -719,9 +734,14 @@ This action supports the following parameters: List Replications ================= -The "listreplication" action is used to retrieve the settings of configured replication tasks. For each task, the response includes the name of the local ZFS pool or dataset to replicate, -the IP address and listening port number of the remote system to replicate to, when the replication occurs (see the "frequency" description in :ref:`Add Replication`), the name of the -dataset on the remote system to store the replicated data ("rdset"), and the name of the replication user account. +The "listreplication" action is used to retrieve the settings of +configured replication tasks. For each task, the response includes the +name of the local ZFS pool or dataset to replicate, the IP address and +listening port number of the remote system to replicate to, when the +replication occurs (see the "frequency" description in +:ref:`Add Replication`), the name of the dataset on the remote system to +store the replicated data ("rdset"), and the name of the replication +user account. **REST Request** @@ -793,7 +813,8 @@ dataset on the remote system to store the replicated data ("rdset"), and the nam Start Replication ================= -The "runreplication" action can be used to manually replicate the specified dataset to the specified remote server. +The "runreplication" action can be used to manually replicate the +specified dataset to the specified remote server. **REST Request** @@ -857,8 +878,10 @@ The "runreplication" action can be used to manually replicate the specified data Initialize Replication ====================== -The "initreplication" action can be used to clear the replication data on the remote server. This is useful if a replication becomes stuck. After running this action, issue a -"runreplication" action to start a new replication. +The "initreplication" action can be used to clear the replication data +on the remote server. This is useful if a replication becomes stuck. +After running this action, issue a "runreplication" action to start a +new replication. The "initreplication" action supports the following parameters: @@ -935,10 +958,15 @@ The "initreplication" action supports the following parameters: View Settings ============= -The "settings" action returns the system-wide settings of the Life Preserver utility. The returned settings include the disk percentage used at which Life Preserver will issue a warning, the -level at which an email will be sent, the email address to send notifications to, and whether or not snapshots are taken recursively (include all child datasets). +The "settings" action returns the system-wide settings of the Life +Preserver utility. The returned settings include the disk percentage +used at which Life Preserver will issue a warning, the level at which an +email will be sent, the email address to send notifications to, and +whether or not snapshots are taken recursively (include all child +datasets). -Run :command:`lpreserver help set` for more information about each available setting. +Run :command:`lpreserver help set` for more information about each +available setting. **REST Request** @@ -1002,7 +1030,9 @@ Run :command:`lpreserver help set` for more information about each available set Save Settings ============= -The "savesettings" action can be used to modify the system-wide settings of the Life Preserver utility. This action supports the following parameters: +The "savesettings" action can be used to modify the system-wide settings +of the Life Preserver utility. This action supports the following +parameters: +---------------------------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Description** | diff --git a/api/classes/logs.rst b/api/classes/logs.rst index fb1da0b..b089505 100644 --- a/api/classes/logs.rst +++ b/api/classes/logs.rst @@ -3,7 +3,8 @@ logs **** -The logs class is used to interact with the log files created by the SysAdm server. +The logs class is used to interact with the log files created by the +SysAdm server. Every logs class request contains the following parameters: @@ -24,7 +25,8 @@ Every logs class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: read_logs, logs @@ -33,20 +35,29 @@ The rest of this section provides examples of the available *actions* for each t Read Logs ========= -The "read_logs" action can be used to display log entries. It supports the following optional arguments: +The "read_logs" action can be used to display log entries. It supports +the following optional arguments: -* **logs:** used to specify an array or string of log type(s). Valid types are "hostinfo", "dispatcher", "events-dispatcher","events-lifepreserver", and "events-state". +* **logs:** used to specify an array or string of log type(s). Valid + types are "hostinfo", "dispatcher", "events-dispatcher", + "events-lifepreserver", and "events-state". -* **time_format:** used to specify the format for "start_time" and "end_time". Valid Formats are "time_t_seconds", "epoch_mseconds, "relative_[day/month/second]", or a - `QDateTime String code `_. +* **time_format:** used to specify the format for "start_time" and + "end_time". Valid Formats are "time_t_seconds", "epoch_mseconds, + "relative_[day/month/second]", or a `QDateTime String code `_. -* **start_time:** displays log entries that occurred after the time specified using a valid "time_format". +* **start_time:** displays log entries that occurred after the time + specified using a valid "time_format". -* **end_time:** displays log entries that occurred before the time specified using a valid "time_format". +* **end_time:** displays log entries that occurred before the time + specified using a valid "time_format". -If the "time_format" is not specified, or if the "start_time" or "end_time" are not defined, the end time will be the current date and time and the start time will be 12 hours previous. +If the "time_format" is not specified, or if the "start_time" or +"end_time" are not defined, the end time will be the current date and +time and the start time will be 12 hours previous. -If the "logs" argument is missing or empty, then all logs matching the search parameters will be returned. +If the "logs" argument is missing or empty, then all logs matching the +search parameters will be returned. For example, this input returns all log entries within the last hour: diff --git a/api/classes/network.rst b/api/classes/network.rst index e65ba52..9caa8ff 100644 --- a/api/classes/network.rst +++ b/api/classes/network.rst @@ -3,7 +3,8 @@ network ******* -The network class is used to manage and retrieve information from Ethernet and wireless network devices. +The network class is used to manage and retrieve information from +Ethernet and wireless network devices. Every network class request contains the following parameters: @@ -24,7 +25,8 @@ Every network class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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-devices, network @@ -33,8 +35,12 @@ The rest of this section provides examples of the available *actions* for each t List Devices ============ -The "list-devices" action lists information about currently recognized network devices. For each network device, the response includes the device's MAC address, description, IPv4 address, -IPv6 address, whether or not the device is active, whether or not the device is configured using DHCP, whether or not the device is wireless, its subnet mask, and its current status. +The "list-devices" action lists information about currently recognized +network devices. For each network device, the response includes the +device's MAC address, description, IPv4 address, IPv6 address, whether +or not the device is active, whether or not the device is configured +using DHCP, whether or not the device is wireless, its subnet mask, and +its current status. **REST Request** diff --git a/api/classes/pkg.rst b/api/classes/pkg.rst index cc69beb..aebee3c 100644 --- a/api/classes/pkg.rst +++ b/api/classes/pkg.rst @@ -25,7 +25,8 @@ Every pkg class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: pkg_info, pkg @@ -34,15 +35,20 @@ The rest of this section provides examples of the available *actions* for each t Package Information =================== -The "pkg_info" action reads the pkg database directly and returns any relevant information. The following arguments are optional: +The "pkg_info" action reads the pkg database directly and returns any +relevant information. The following arguments are optional: * **"repo"**: unless specified, defaults to the local package repository. -* **"pkg_origins"**: unless specified, information for all installed packages will be listed. +* **"pkg_origins"**: unless specified, information for all installed + packages will be listed. -* **"category"**: limits the results to packages within the specified category. +* **"category"**: limits the results to packages within the specified + category. -* **"result"**: must be set to "full" to retrieve all of the information with multiple possible values, such as "dependencies", "options", and "licences". +* **"result"**: must be set to "full" to retrieve all of the information + with multiple possible values, such as "dependencies", "options", and + "licences". **REST Request** @@ -231,11 +237,14 @@ The "pkg_info" action reads the pkg database directly and returns any relevant i Search Packages =============== -The "pkg_search" action searches the package database for pkgs which match the given "search_term" (required). These parameters are optional: +The "pkg_search" action searches the package database for pkgs which +match the given "search_term" (required). These parameters are optional: -* **"repo"**: may be used to specifiy searching the specified repository. If not specified, the local package database is searched. +* **"repo"**: may be used to specifiy searching the specified repository. + If not specified, the local package database is searched. -* **"category"**: may be used to restrict searches to the specified package category. +* **"category"**: may be used to restrict searches to the specified + package category. **REST Request** @@ -412,7 +421,9 @@ The "pkg_search" action searches the package database for pkgs which match the g List Categories =============== -The "list_categories" action lists all the known, non-empty categories within the specified repository or, if no repository is specified, the local repository. +The "list_categories" action lists all the known, non-empty categories +within the specified repository or, if no repository is specified, the +local repository. **REST Request** @@ -511,8 +522,10 @@ The "list_categories" action lists all the known, non-empty categories within th List Repositories ================= -The "list_repositories" action scan the package repository configuration files and returns the names of the available repositories. All of the repositories returned by this -action are valid as the optional "repo" argument for the other pkg API actions. +The "list_repositories" action scan the package repository configuration +files and returns the names of the available repositories. All of the +repositories returned by this action are valid as the optional "repo" +argument for the other pkg API actions. **REST Request** @@ -559,10 +572,16 @@ action are valid as the optional "repo" argument for the other pkg API actions. Audit Packages ============== -The "pkg_audit" action performs an audit of all installed packages and reports any packages with known vulnerabilities as well as other packages which are impacted by those vulnerabilities. +The "pkg_audit" action performs an audit of all installed packages and +reports any packages with known vulnerabilities as well as other +packages which are impacted by those vulnerabilities. -.. note:: the vulnerability information will be returned as a dispatcher event as this action just queues up the results of the :command:`pkg` operation. This is due to a limitation of - :command:`pkg`, as it only supports one process call at a time. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events. +.. note:: the vulnerability information will be returned as a dispatcher + event as this action just queues up the results of the :command:`pkg` + operation. This is due to a limitation of :command:`pkg`, as it only + supports one process call at a time. Refer to the + :ref:`Dispatcher Subsystem` for instructions on how to subscribe to + and query dispatcher events. **REST Request** @@ -634,8 +653,10 @@ The "pkg_audit" action performs an audit of all installed packages and reports a Upgrade Packages ================ -The "pkg_upgrade" action upgrades all currently installed packages. The messages from the upgrade will be returned as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for -instructions on how to subscribe to and query dispatcher events. +The "pkg_upgrade" action upgrades all currently installed packages. The +messages from the upgrade will be returned as a dispatcher event. Refer +to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe +to and query dispatcher events. **REST Request** @@ -707,8 +728,10 @@ instructions on how to subscribe to and query dispatcher events. Check Packages ============== -The "pkg_check_upgrade" action checks to see if there are any package updates available and returns that information as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for -instructions on how to subscribe to and query dispatcher events. +The "pkg_check_upgrade" action checks to see if there are any package +updates available and returns that information as a dispatcher event. +Refer to the :ref:`Dispatcher Subsystem` for instructions on how to +subscribe to and query dispatcher events. **REST Request** @@ -781,10 +804,14 @@ instructions on how to subscribe to and query dispatcher events. Update Package Database ======================= -The "pkg_update" action instructs :command:`pkg` to update its databases. This action is typically not required. It returns any information as a dispatcher event. Refer to the -:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events. +The "pkg_update" action instructs :command:`pkg` to update its databases. +This action is typically not required. It returns any information as a +dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for +instructions on how to subscribe to and query dispatcher events. -If you include "force" = "true", it forces :command:`pkg` to completely resync all of its databases with all known repositories which may take some time. +If you include "force" = "true", it forces :command:`pkg` to completely +resync all of its databases with all known repositories which may take +some time. **REST Request** @@ -858,12 +885,17 @@ If you include "force" = "true", it forces :command:`pkg` to completely resync a Lock/Unlock Packages ==================== -The "pkg_lock" action locks the specified "pkg_origins" so that it will be skipped during a package upgrade and remain at its current version. When using "pkg_origins", specify either a -single package origin string or an array of package origins. +The "pkg_lock" action locks the specified "pkg_origins" so that it will +be skipped during a package upgrade and remain at its current version. +When using "pkg_origins", specify either a single package origin string +or an array of package origins. -The "pkg_unlock" action unlocks the previously locked "pkg_origins" so that it is no longer skipped during a package upgrade. +The "pkg_unlock" action unlocks the previously locked "pkg_origins" so +that it is no longer skipped during a package upgrade. -Both actions return any information as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events. +Both actions return any information as a dispatcher event. Refer to the +:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and +query dispatcher events. **REST Request** @@ -1006,9 +1038,13 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di Install Packages ================ -The "pkg_install" action installs the specified "pkg_origins" on the system. When using "pkg_origins", specify either a single package origin string or an array of package origins. -Unless the "repo" is specified, :command:`pkg` will automatically determine the repository. The install messages will be returned as a dispatcher event. Refer to the -:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events. +The "pkg_install" action installs the specified "pkg_origins" on the +system. When using "pkg_origins", specify either a single package origin +string or an array of package origins. Unless the "repo" is specified, +:command:`pkg` will automatically determine the repository. The install +messages will be returned as a dispatcher event. Refer to the +:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and +query dispatcher events. **REST Request** @@ -1084,12 +1120,17 @@ Unless the "repo" is specified, :command:`pkg` will automatically determine the Uninstall Packages ================== -The "pkg_remove" action uninstalls the specified "pkg_origins" from the system. When using "pkg_origins", specify either a single package origin string or an array of package origins. +The "pkg_remove" action uninstalls the specified "pkg_origins" from the +system. When using "pkg_origins", specify either a single package origin +string or an array of package origins. -The optional "recursive" argument can be set to "true" or "false". The default is "true", which means that other packages which depend on this package will also be removed so that there are -no broken dependencies. +The optional "recursive" argument can be set to "true" or "false". The +default is "true", which means that other packages which depend on this +package will also be removed so that there are no broken dependencies. -The uninstall messages will be returned as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events. +The uninstall messages will be returned as a dispatcher event. Refer to +the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to +and query dispatcher events. **REST Request** diff --git a/api/classes/systemmanager.rst b/api/classes/systemmanager.rst index f554aaa..c131bd1 100644 --- a/api/classes/systemmanager.rst +++ b/api/classes/systemmanager.rst @@ -3,7 +3,8 @@ systemmanager ************* -The systemmanager class is used to retrieve information about the system. Every systemmanager class request contains the following parameters: +The systemmanager class is used to retrieve information about the system. +Every systemmanager class request contains the following parameters: +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Value** | **Description** | @@ -23,7 +24,8 @@ The systemmanager class is used to retrieve information about the system. Every | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: memorystats, systemmanager @@ -32,7 +34,8 @@ The rest of this section provides examples of the available *actions* for each t Memory Statistics ================= -The "memorystats" action returns memory statistics, including the amount of active, cached, free, inactive, and total physical (wired) memory. +The "memorystats" action returns memory statistics, including the amount +of active, cached, free, inactive, and total physical (wired) memory. **REST Request** @@ -244,8 +247,10 @@ The "cputemps" action returns the temperature of each CPU. Process Information =================== -The "procinfo" action lists information about each running process. Since a system will have many running processes, the responses in this section only show one process as an example -of the type of information listed by this action. +The "procinfo" action lists information about each running process. +Since a system will have many running processes, the responses in this +section only show one process as an example of the type of information +listed by this action. **REST Request** @@ -326,7 +331,9 @@ of the type of information listed by this action. Kill a Process ============== -The "killproc" action can be used to send the specified signal to the specified Process ID (PID). The following signals are supported: INT, QUIT, ABRT, KILL, ALRM, or TERM. +The "killproc" action can be used to send the specified signal to the +specified Process ID (PID). The following signals are supported: INT, +QUIT, ABRT, KILL, ALRM, or TERM. **REST Request** @@ -392,8 +399,10 @@ The "killproc" action can be used to send the specified signal to the specified Battery Information =================== -The "batteryinfo" action will indicate whether or not a battery exists. If it does, it will also report its current charge percentage level (1-99). its -status (offline, charging, on backup, or unknown), and estimated time left (in seconds). +The "batteryinfo" action will indicate whether or not a battery exists. +If it does, it will also report its current charge percentage level +(1-99). its status (offline, charging, on backup, or unknown), and +estimated time left (in seconds). **REST Request** @@ -451,8 +460,10 @@ status (offline, charging, on backup, or unknown), and estimated time left (in s List External Mounts ==================== -The "externalmounts" action returns a list of mounted external devices. Supported device types are UNKNOWN, USB, HDRIVE (external hard drive), DVD, and SDCARD. -For each mounted device, the response will include the device name, filesystem, mount path, and device type. +The "externalmounts" action returns a list of mounted external devices. +Supported device types are UNKNOWN, USB, HDRIVE (external hard drive), +DVD, and SDCARD. For each mounted device, the response will include the +device name, filesystem, mount path, and device type. **REST Request** @@ -518,8 +529,10 @@ For each mounted device, the response will include the device name, filesystem, System Information ================== -The "systemmanager" action lists system information, including the architecture, number of CPUs, type of CPU, hostname, kernel name and version, system version and patch level, total amount -of RAM, and the system's uptime. +The "systemmanager" action lists system information, including the +architecture, number of CPUs, type of CPU, hostname, kernel name and +version, system version and patch level, total amount of RAM, and the +system's uptime. **REST Request** @@ -593,7 +606,9 @@ of RAM, and the system's uptime. List Sysctls ============ -The "sysctllist" action lists returns the list of all setable sysctl values. Since there are many, the example responses in this section have been truncated to just show a few. +The "sysctllist" action lists returns the list of all setable sysctl +values. Since there are many, the example responses in this section have +been truncated to just show a few. **REST Request** @@ -667,7 +682,9 @@ The "sysctllist" action lists returns the list of all setable sysctl values. Sin Set a Sysctl ============ -The "setsysctl" action sets the specified setable sysctl to the specified value. The response indicates that the old value was changed to the new value. +The "setsysctl" action sets the specified setable sysctl to the +specified value. The response indicates that the old value was changed +to the new value. **REST Request** diff --git a/api/classes/updates.rst b/api/classes/updates.rst index 12a7051..b3073b7 100644 --- a/api/classes/updates.rst +++ b/api/classes/updates.rst @@ -3,7 +3,8 @@ update ****** -The update class is used to check for and manage system and software updates. +The update class is used to check for and manage system and software +updates. Every update class request contains the following parameters: @@ -24,7 +25,8 @@ Every update class request contains the following parameters: | | | | +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -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:: checkupdates, update @@ -33,8 +35,11 @@ The rest of this section provides examples of the available *actions* for each t Check for Updates ================= -The "checkupdates" action queries the update server to see if any updates are available. If an update is available, the response will indicate if it is a system security update, an -upgrade to a newer version of the operating system, a system patch, or an update to installed software packages. +The "checkupdates" action queries the update server to see if any +updates are available. If an update is available, the response will +indicate if it is a system security update, an upgrade to a newer +version of the operating system, a system patch, or an update to +installed software packages. **REST Request** @@ -92,7 +97,9 @@ upgrade to a newer version of the operating system, a system patch, or an update List Branches ============= -The "listbranches" action retrieves the list of available branches (operating system versions). The currently installed version will be listed as "active". +The "listbranches" action retrieves the list of available branches +(operating system versions). The currently installed version will be +listed as "active". **REST Request** @@ -152,17 +159,24 @@ The "listbranches" action retrieves the list of available branches (operating sy Start Updates ============= -The "startupdate" action starts the specified update. You must specify a "target" to indicate the type of update to perform. The available targets are: +The "startupdate" action starts the specified update. You must specify a +"target" to indicate the type of update to perform. The available +targets are: -* **chbranch:** will update to the specified "branch" (operating system version). You can determine which branches are available by using the "listbranches" action. +* **chbranch:** will update to the specified "branch" (operating system + version). You can determine which branches are available by using the + "listbranches" action. * **pkgupdate:** only update installed software. * **fbsdupdate:** only apply FreeBSD system updates. -* **fbsdupdatepkgs:** update installed software and apply FreeBSD system updates. +* **fbsdupdatepkgs:** update installed software and apply FreeBSD system + updates. -* **standalone:** only apply the update specified as a "tag". Use the "checkupdates" action to determine the name (tag) of the update to specify. +* **standalone:** only apply the update specified as a "tag". Use the + "checkupdates" action to determine the name (tag) of the update to + specify. **REST Request** diff --git a/api/classes/zfs.rst b/api/classes/zfs.rst index e1c2ed8..7e5894b 100644 --- a/api/classes/zfs.rst +++ b/api/classes/zfs.rst @@ -7,24 +7,25 @@ The zfs class is used to manage and retrieve information about ZFS pools. Every zfs class request contains the following parameters: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | zfs | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | sysadm | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| action | | supported actions include "list_pools", "datasets" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++=================================+===============+==============================================================================+ +| id | | any unique value for the request; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| name | zfs | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| namespace | sysadm | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| action | | supported actions include "list_pools", "datasets" | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ -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_pools, zfs @@ -33,9 +34,14 @@ The rest of this section provides examples of the available *actions* for each t List Pools ========== -The "list_pools" action lists pool information. For each ZFS pool, the response includes the pool name, the amount of space that has been physically allocated, whether or not an alternate -root has been defined, capacity (percent used), the deduplication ratio, amount of uninitialized space (expandsz, which usually applies to LUNs), percentage of fragmentation, amount of free -space, pool health, and total size. This action is the equivalent of running :command:`zpool list` from the command line. +The "list_pools" action lists pool information. For each ZFS pool, the +response includes the pool name, the amount of space that has been +physically allocated, whether or not an alternate root has been defined, +capacity (percent used), the deduplication ratio, amount of +uninitialized space (expandsz, which usually applies to LUNs), +percentage of fragmentation, amount of free space, pool health, and +total size. This action is the equivalent of running +:command:`zpool list` from the command line. **REST Request** diff --git a/api/connection.rst b/api/connection.rst index faf55a1..45a4cc5 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -5,45 +5,53 @@ Getting Started .. Some intro text here... -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. +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. .. Add some links to docs on websockets and json -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 following parameters: +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: -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | auth | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | rpc | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| args | | values vary by type of authentication request | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| **Parameter** | **Value** | **Description** | +| | | | ++=================================+===============+==============================================================================+ +| id | | any unique value for the request; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| name | auth | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| namespace | rpc | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| args | | values vary by type of authentication request | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ -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 username/password requests are server side only. +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 username/password requests are server side only. -.. note:: individual servers can be configured to refuse username and password requests altogether. +.. note:: individual servers can be configured to refuse username and + password requests altogether. **1. Username and Password:** @@ -61,7 +69,8 @@ by both server and bridge, while token authentication and username/password requ } } -.. note:: when connecting to the localhost, the password field may be left empty for non-root user access. +.. note:: when connecting to the localhost, the password field may be + left empty for non-root user access. **2. Token Authentication: (Server only)** @@ -78,8 +87,10 @@ by both server and bridge, while token authentication and username/password requ } } -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. +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)** @@ -107,9 +118,12 @@ left to automated systems 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 accurate transport -back to the server. +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)** @@ -140,11 +154,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 after 10 minutes of inactivity. +.. 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 + 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, looks like this: **WebSocket Reply** @@ -160,7 +180,8 @@ An invalid authentication, or a system request after the user session has timed "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, use this +request: **WebSocket Request** @@ -175,9 +196,15 @@ To clear a pre-saved authentication token, such as signing out, use this request -**3.2. Alternate SSL Certificate Authentication Initiation (server through bridge)** +**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 connection. +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)** @@ -209,33 +236,44 @@ This is an alternate method for stage 1 of the SSL Certificate Authentication me } -.. 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. +.. 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. .. _SSL Certificate Management: SSL Certificate Management ========================== -Several actions are available for managing the SSL certificates used for authentication. +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 | | supported 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 @@ -244,7 +282,9 @@ The rest of this section provides examples of the available *actions* for each t List SSL Certificates --------------------- -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. +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** @@ -283,9 +323,12 @@ The "list_ssl_certificates" action lists the known and registered certificates. 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 loaded into the server/client -connection. +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 +loaded into the server/client connection. **Websocket Request** @@ -315,7 +358,8 @@ connection. } -.. 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 @@ -324,9 +368,13 @@ 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 "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 user. +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 +user. **Websocket Request** @@ -354,9 +402,14 @@ revoke a certificate belonging to another user. "args" : {} } -.. 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 has full administrative - access; otherwise, it may only be used to manage the current user's certificates. +.. 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 + has full administrative access; otherwise, it may only be used + to manage the current user's certificates. .. index:: dispatcher, events @@ -365,31 +418,37 @@ revoke a certificate belonging to another user. Dispatcher Subsystem ==================== -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 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. -.. 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. +.. 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; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| name | subscribe | use the desired action | +| | unsubscribe | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| namespace | events | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| args | dispatcher | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ For example, to subscribe to dispatcher events: @@ -402,8 +461,10 @@ 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 dispatcher events: +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 @@ -430,22 +491,22 @@ This response indicates that a dispatcher event occurred: A "dispatcher" query contains the following 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; examples include a hash, checksum, or uuid | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| name | dispatcher | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| namespace | events | | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ +| action | | "run" is used to submit process commands | +| | | | ++---------------------------------+---------------+------------------------------------------------------------------------------+ Dispatcher events have the following syntax: @@ -467,7 +528,8 @@ Dispatcher events have the following syntax: } } -Any user within the *wheel* group can use the "run" action to submit a new job to the dispatcher: +Any user within the *wheel* group can use the "run" action to submit a +new job to the dispatcher: **REST Request** @@ -531,41 +593,51 @@ Any user within the *wheel* group can use the "run" action to submit a new job t "namespace": "rpc" } -When submitting a job to the dispatcher, keep the following points in mind: +When submitting a job to the dispatcher, keep the following points in +mind: -* 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 dispatcher process. +* 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 + 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), or until there are no more commands to run. +* 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), + or until there are no more commands to run. -* A chain of commands is useful for multi-step operations but is not considered a replacement for a good shell script on the server. +* 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 subsystems. This namespace supports the following parameters: +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; examples include 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 @@ -574,7 +646,9 @@ The rest of this section provides examples of the available *names* for each typ 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 access the user has. This subsystem is used only by the server. +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** @@ -634,7 +708,9 @@ An RPC query can be issued to probe all the known subsystems and return which on Identify Subsystem ------------------ -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. +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** @@ -674,7 +750,8 @@ To identify the type of SysAdm system, use :command:`identify`. Possible identit 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** diff --git a/api/events.rst b/api/events.rst index a275f7c..51139d8 100644 --- a/api/events.rst +++ b/api/events.rst @@ -3,33 +3,37 @@ Events ====== -The "events" namespace can be used to setup and receive asynchronous updates about system status and other types of system notifications. +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. +.. 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. Every events request contains the following 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; examples include 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. The following is a template to subscribe to various +subsystem event notifications: **Websocket Request** @@ -42,7 +46,9 @@ The following is a template to subscribe to various subsystem event notification "args" : ["dispatcher", "life-preserver", "system-state"] } -Once subscribed, events will be received as they are produced. To unsubscribe from events, repeat the request, using "unsubscribe" for the "name". +Once subscribed, events will be received as they are produced. To +unsubscribe from events, repeat the request, using "unsubscribe" for the +"name". Here is an example reply from the Life Preserver subsystem: @@ -65,9 +71,11 @@ Here is an example reply from the Life Preserver subsystem: 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 the following: +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 +the following: **Websocket Request** @@ -80,9 +88,10 @@ To subscribe to the Dispatcher subsystem for event updates, use the following: "args" : ["dispatcher"] } -The Dispatcher event log will display three different states: "pending", "running", and "finished". -Depending upon the current state, the log can change in some minor but noteworthy ways. -The following sample logs will reflect the differences between these states: +The Dispatcher event log will display three different states: "pending", +"running", and "finished". Depending upon the current state, the log can +change in some minor but noteworthy ways. The following sample logs will +reflect the differences between these states: **Dispatcher Response: "Pending" state** @@ -138,9 +147,10 @@ The following sample logs will 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. A generalized +sample is as follows: **Dispatcher Class Event Message** @@ -158,12 +168,14 @@ A generalized sample is as follows: } } -For specific details on these special types of events please refer to the Classes section of this User Guide. +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 following: +To subscribe to the Life Preserver subsystem for event updates, use the +following: **Websocket Request** @@ -195,7 +207,8 @@ To subscribe to the Life Preserver subsystem for event updates, use the followin System State ------------ -To subscribe to the System State subsystem for event updates, use the following: +To subscribe to the System State subsystem for event updates, use the +following: **Websocket Request** @@ -239,8 +252,11 @@ To subscribe to the System State subsystem for event updates, use the following: 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 server connects/disconnects or vice versa. +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** @@ -255,4 +271,6 @@ A client will only get the event when a server connects/disconnects or vice vers } } -.. 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 +.. 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 diff --git a/docs/basics.rst b/docs/basics.rst index 237e9d2..84e1c0f 100644 --- a/docs/basics.rst +++ b/docs/basics.rst @@ -12,7 +12,8 @@ SysAdm™ files are currently available from the `github repository `, replacing and with the server key filename and location. Once the server key file is successfully imported, start the bridge (if not already running). +Now, we must transition to the bridge to import the server key. Login to +the bridge as the administrator (or root), then type +:command:`sysadm-bridge import_ssl_file `, +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. +.. note:: The bridge can import SSL files whether it is active or not + with no negative effects. -Back on the server, run :command:`sudo sysadm-binary bridge_add ` to point the server at the bridge. A bridge runs on **port 12149** by default, so the URL will likely need **:12149** added on the end of the address (Example URL: 127.0.0.1:12149). If necessary, (re)start the server. The log (:file:`/var/log/sysadm-server-ws.log`) will display messages about connecting to the bridge. -If properly configured, the server and bridge will now be communicating with each other. At this point clients can be added to the mix which will communicate with the server through the bridge. +Back on the server, run :command:`sudo sysadm-binary bridge_add ` +to point the server at the bridge. A bridge runs on **port 12149** by +default, so the URL will likely need **:12149** added on the end of the +address (Example URL: 127.0.0.1:12149). If necessary, (re)start the +server. The log (:file:`/var/log/sysadm-server-ws.log`) will display +messages about connecting to the bridge. If properly configured, the +server and bridge will now be communicating with each other. At this +point clients can be added to the mix which will communicate with the +server through the bridge. .. _add client: Adding a Client to the Server/Bridge Connection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: If you have an old SSL bundle from a pre-alpha version of SysAdm created before June 2016, it will need to be removed prior to proceeding with the client initialization process. +.. note:: If you have an old SSL bundle from a pre-alpha version of + SysAdm created before June 2016, it will need to be removed + prior to proceeding with the client initialization process. -In the client UI, create or import an SSL key bundle as prompted by the UI. Once the new SSL keys are created, open :menuselection:`Setup SSL --> View Certificates` in the connection manager and click "Export Public Key" for both the server and bridge keys. This will export both SSL keys in file form, depositing them in either the "Desktop" folder or home directory (depending on operating system). If necessary, send these key files as an email attachment to the system administrator as part of a request for server/bridge access. +In the client UI, create or import an SSL key bundle as prompted by the +UI. Once the new SSL keys are created, open +:menuselection:`Setup SSL --> View Certificates` in the connection +manager and click "Export Public Key" for both the server and bridge +keys. This will export both SSL keys in file form, depositing them in +either the "Desktop" folder or home directory (depending on operating +system). If necessary, send these key files as an email attachment to +the system administrator as part of a request for server/bridge access. -Moving to the bridge, as the administrator (or root), run :command:`sysadm-bridge import_ssl_file ` for the requesting client's bridge key file. Now the client and bridge should be able to communicate, but the client/server connection still needs to be established. +Moving to the bridge, as the administrator (or root), run +:command:`sysadm-bridge import_ssl_file ` for the +requesting client's bridge key file. Now the client and bridge should be +able to communicate, but the client/server connection still needs to be +established. -On the server, run :command:`sudo sysadm-binary import_ssl_key []` to import the client -> server SSL key file. This grants an individual with that specific SSL authorization the same permissions as . +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. +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/introduction.rst b/docs/introduction.rst index c786686..17e62db 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -12,10 +12,26 @@ Version |version| Copyright © 2016 iXSystems®. -.. Intro Text WIP. Needed is a full description of what sysadm is and what it can do. SysAdm is a middleware utility designed to provide a user access to firewalled servers and systems from any location with an open access point to the internet. To accomplish this goal, a bridge device has been created, which relays all traffic between the firewalled system and the user's controlling device. In order to address security concerns, the bridge device is always considered "untrusted" and several layers of encryption are added to all traffic flowing through the bridge to ensure the bridge can not be used to record or alter critical information flow. Once a secure connection has been established, a user can fully control a firewalled system or group of systems through the SysAdm utility. Installing packages, creating work tasks, running build servers and automation; controlling a secure system from any Internet connected location with minimal risk of a security breach is the ultimate goal of SysAdm. +.. Intro Text WIP. Needed is a full description of what sysadm is and + what it can do. SysAdm is a middleware utility designed to provide a + user access to firewalled servers and systems from any location with + an open access point to the internet. To accomplish this goal, a + bridge device has been created, which relays all traffic between the + firewalled system and the user's controlling device. In order to + address security concerns, the bridge device is always considered + "untrusted" and several layers of encryption are added to all traffic + flowing through the bridge to ensure the bridge can not be used to + record or alter critical information flow. Once a secure connection + has been established, a user can fully control a firewalled system or + group of systems through the SysAdm utility. Installing packages, + creating work tasks, running build servers and automation; + controlling a secure system from any Internet connected location with + minimal risk of a security breach is the ultimate goal of SysAdm. -Welcome to SysAdm™! This documentation is intended to educate the user on initializing and managing the SysAdm™ middleware. -Initialization and management will be documented in two separate chapters, :ref:`gettingstarted`, and :ref:`management`. -API documentation is being handled at https://api.pcbsd.org. +Welcome to SysAdm™! This documentation is intended to educate the user +on initializing and managing the SysAdm™ middleware. Initialization and +management will be documented in two separate chapters, +:ref:`gettingstarted`, and :ref:`management`. API documentation is being +handled at https://api.pcbsd.org. diff --git a/docs/manage.rst b/docs/manage.rst index 58b05eb..1e6ca11 100644 --- a/docs/manage.rst +++ b/docs/manage.rst @@ -3,10 +3,12 @@ SysAdm™ Management ================== -SysAdm™ comes with a standard configuration file located at :file:`/usr/local/etc/sysadm.conf.dist`. +SysAdm™ comes with a standard configuration file located at +:file:`/usr/local/etc/sysadm.conf.dist`. -It is possible to edit this file for a custom configuration, but the result will need to be saved as :kbd:`sysadm.conf`. -Here is the current default settings for SysAdm™:: +It is possible to edit this file for a custom configuration, but the +result will need to be saved as :kbd:`sysadm.conf`. Here are the current +default settings for SysAdm™:: #Sample Configuration file for the sysadm server @@ -21,10 +23,14 @@ This default configuration also has blacklist options, recreated here:: ### Blacklist options ### # - Number of minutes that an IP remains on the blacklist BLACKLIST_BLOCK_MINUTES=60 - # - Number of authorization failures before an IP is placed on the blacklist + # - Number of authorization failures before an IP is placed on the + blacklist BLACKLIST_AUTH_FAIL_LIMIT=5 - # - Number of minutes of no activity from an IP before resetting the failure counter - # (Note: A successful authorization will always reset the fail counter) + # - Number of minutes of no activity from an IP before resetting the + failure counter + # (Note: A successful authorization will always reset the fail + counter) BLACKLIST_AUTH_FAIL_RESET_MINUTES=10 -Please note these default options are subject to change as the SysAdm™ utility is developed. \ No newline at end of file +Please note these default options are subject to change as the SysAdm™ +utility is developed. \ No newline at end of file