github-personal/sysadm
1
0
Fork 0
mirror of https://github.com/outbackdingo/sysadm.git synced 2026-01-27 02:20:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

SysAdm PEP8 Conversion

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

31
api/classes/beadm.rst
View File

@@ -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**

15
api/classes/dispatcher.rst
View File

@@ -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**

3
api/classes/fs.rst
View File

@@ -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

91
api/classes/iocage.rst
View File

@@ -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) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
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) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
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) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_ 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) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_
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**

50
api/classes/iohyve.rst
View File

@@ -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 <name>` 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 <name>` 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**

78
api/classes/lifepreserver.rst
View File

@@ -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** |

31
api/classes/logs.rst
View File

@@ -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 <http://doc.qt.io/qt-5/qdatetime.html#fromString>`_.
* **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 <http://doc.qt.io/qt-5/qdatetime.html#fromString>`_.
* **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:

14
api/classes/network.rst
View File

@@ -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**

105
api/classes/pkg.rst
View File

@@ -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**

45
api/classes/systemmanager.rst
View File

@@ -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**

32
api/classes/updates.rst
View File

@@ -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**

46
api/classes/zfs.rst
View File

@@ -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**

351
api/connection.rst
View File

@@ -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 "<binary/utility> <list of arguments>", 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 "<binary/utility> <list of arguments>",
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**

92
api/events.rst
View File

@@ -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.
.. 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.

79
docs/basics.rst
View File

@@ -12,7 +12,8 @@ SysAdm™ files are currently available from the `github repository <https://git
Building SysAdm™
----------------
The following Qt Modules are required before attempting to build SysAdm™: ::
The following Qt Modules are required before attempting to build
SysAdm™: ::
Qt5 Core (# pkg install qt5-core)
Qt5 Concurrent (# pkg install qt5-concurrent)
@@ -20,7 +21,8 @@ The following Qt Modules are required before attempting to build SysAdm™: ::
Qt5 Sql (# pkg install qt5-sql)
Qt5 Websockets (# pkg install qt5-websockets)
Building the prototype version of SysAdm™ assumes you have access to github.com. ::
Building the prototype version of SysAdm™ assumes you have access to
github.com. ::
% git clone https://github.com/pcbsd/sysadm.git
% cd sysadm/src
@@ -32,7 +34,8 @@ Building the prototype version of SysAdm™ assumes you have access to github.co
Starting SysAdm™
----------------
SysAdm can be started one of two ways: 1. The traditional rc(8) mechanism 2. The new jobd(8) mechanism
SysAdm can be started one of two ways: 1. The traditional rc(8)
mechanism 2. The new jobd(8) mechanism
To run under rc(8)::
@@ -58,40 +61,84 @@ To run under jobd(8)::
Bridge Initialization
---------------------
Configuring and connecting to a bridge can be a complicated process. Thankfully, there are several steps that are done the first time a server and bridge are configured with SysAdm but do not need to be repeated later. Once these steps are complete, it becomes a much simpler process for a new user to configure their client to communicate with the now configured server and bridge.
Configuring and connecting to a bridge can be a complicated process.
Thankfully, there are several steps that are done the first time a
server and bridge are configured with SysAdm but do not need to be
repeated later. Once these steps are complete, it becomes a much simpler
process for a new user to configure their client to communicate with the
now configured server and bridge.
.. note:: A list of current commands is available by typing :command:`-h` after the utility name (Example: :command:`sysadm-bridge -h`).
.. note:: A list of current commands is available by typing :command:`-h`
after the utility name (Example: :command:`sysadm-bridge -h`).
.. _serverbridge init:
Server and Bridge Initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To initialize the server and bridge, begin with the server. Run :command:`sudo sysadm-binary bridge_export_key [optional absolute file path]`. This will export the public SSL key the server uses to authenticate with the bridge.
To initialize the server and bridge, begin with the server. Run
:command:`sudo sysadm-binary bridge_export_key [optional absolute file path]`.
This will export the public SSL key the server uses to authenticate with
the bridge.
.. note:: For both server and client, giving SSL key files an easy to remember name and location will simplify the process of finding those files for import to the bridge.
.. note:: For both server and client, giving SSL key files an easy to
remember name and location will simplify the process of
finding those files for import to the bridge.
Now, we must transition to the bridge to import the server key. Login to the bridge as the administrator (or root), then type :command:`sysadm-bridge import_ssl_file <filename> <filepath>`, replacing <filename> and <filepath> with the server key filename and location. Once the server key file is successfully imported, start the bridge (if not already running).
Now, we must transition to the bridge to import the server key. Login to
the bridge as the administrator (or root), then type
:command:`sysadm-bridge import_ssl_file <filename> <filepath>`,
replacing <filename> and <filepath> with the server key filename and
location. Once the server key file is successfully imported, start the
bridge (if not already running).
.. note:: The bridge can import SSL files whether it is active or not with no negative effects.
.. note:: The bridge can import SSL files whether it is active or not
with no negative effects.
Back on the server, run :command:`sudo sysadm-binary bridge_add <nickname> <URL>` to point the server at the bridge. A bridge runs on **port 12149** by default, so the URL will likely need **:12149** added on the end of the address (Example URL: 127.0.0.1:12149). If necessary, (re)start the server. The log (:file:`/var/log/sysadm-server-ws.log`) will display messages about connecting to the bridge.
If properly configured, the server and bridge will now be communicating with each other. At this point clients can be added to the mix which will communicate with the server through the bridge.
Back on the server, run :command:`sudo sysadm-binary bridge_add <nickname> <URL>`
to point the server at the bridge. A bridge runs on **port 12149** by
default, so the URL will likely need **:12149** added on the end of the
address (Example URL: 127.0.0.1:12149). If necessary, (re)start the
server. The log (:file:`/var/log/sysadm-server-ws.log`) will display
messages about connecting to the bridge. If properly configured, the
server and bridge will now be communicating with each other. At this
point clients can be added to the mix which will communicate with the
server through the bridge.
.. _add client:
Adding a Client to the Server/Bridge Connection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note:: If you have an old SSL bundle from a pre-alpha version of SysAdm created before June 2016, it will need to be removed prior to proceeding with the client initialization process.
.. note:: If you have an old SSL bundle from a pre-alpha version of
SysAdm created before June 2016, it will need to be removed
prior to proceeding with the client initialization process.
In the client UI, create or import an SSL key bundle as prompted by the UI. Once the new SSL keys are created, open :menuselection:`Setup SSL --> View Certificates` in the connection manager and click "Export Public Key" for both the server and bridge keys. This will export both SSL keys in file form, depositing them in either the "Desktop" folder or home directory (depending on operating system). If necessary, send these key files as an email attachment to the system administrator as part of a request for server/bridge access.
In the client UI, create or import an SSL key bundle as prompted by the
UI. Once the new SSL keys are created, open
:menuselection:`Setup SSL --> View Certificates` in the connection
manager and click "Export Public Key" for both the server and bridge
keys. This will export both SSL keys in file form, depositing them in
either the "Desktop" folder or home directory (depending on operating
system). If necessary, send these key files as an email attachment to
the system administrator as part of a request for server/bridge access.
Moving to the bridge, as the administrator (or root), run :command:`sysadm-bridge import_ssl_file <nickname> <filepath>` for the requesting client's bridge key file. Now the client and bridge should be able to communicate, but the client/server connection still needs to be established.
Moving to the bridge, as the administrator (or root), run
:command:`sysadm-bridge import_ssl_file <nickname> <filepath>` for the
requesting client's bridge key file. Now the client and bridge should be
able to communicate, but the client/server connection still needs to be
established.
On the server, run :command:`sudo sysadm-binary import_ssl_key <username> <filepath> [<email>]` to import the client -> server SSL key file. This grants an individual with that specific SSL authorization the same permissions as <user>.
On the server, run :command:`sudo sysadm-binary import_ssl_key <username> <filepath> [<email>]`
to import the client -> server SSL key file. This grants an individual
with that specific SSL authorization the same permissions as <user>.
Back in the user client, open the connection manager and choose "Bridge Relay" as the connection option. Input the established bridge's URL and click "Connect".The bridge will now show up in the menu tree with a different icon, and will have a sub-menu of connections within it. If you click on the bridged system, it will open the standard UI but the connection is still being relayed through the bridge.
Back in the user client, open the connection manager and choose "Bridge
Relay" as the connection option. Input the established bridge's URL and
click "Connect".The bridge will now show up in the menu tree with a
different icon, and will have a sub-menu of connections within it. If
you click on the bridged system, it will open the standard UI but the
connection is still being relayed through the bridge.
.. _adddoc:

24
docs/introduction.rst
View File

@@ -12,10 +12,26 @@ Version |version|
Copyright © 2016 iXSystems®.
.. Intro Text WIP. Needed is a full description of what sysadm is and what it can do. SysAdm is a middleware utility designed to provide a user access to firewalled servers and systems from any location with an open access point to the internet. To accomplish this goal, a bridge device has been created, which relays all traffic between the firewalled system and the user's controlling device. In order to address security concerns, the bridge device is always considered "untrusted" and several layers of encryption are added to all traffic flowing through the bridge to ensure the bridge can not be used to record or alter critical information flow. Once a secure connection has been established, a user can fully control a firewalled system or group of systems through the SysAdm utility. Installing packages, creating work tasks, running build servers and automation; controlling a secure system from any Internet connected location with minimal risk of a security breach is the ultimate goal of SysAdm.
.. Intro Text WIP. Needed is a full description of what sysadm is and
what it can do. SysAdm is a middleware utility designed to provide a
user access to firewalled servers and systems from any location with
an open access point to the internet. To accomplish this goal, a
bridge device has been created, which relays all traffic between the
firewalled system and the user's controlling device. In order to
address security concerns, the bridge device is always considered
"untrusted" and several layers of encryption are added to all traffic
flowing through the bridge to ensure the bridge can not be used to
record or alter critical information flow. Once a secure connection
has been established, a user can fully control a firewalled system or
group of systems through the SysAdm utility. Installing packages,
creating work tasks, running build servers and automation;
controlling a secure system from any Internet connected location with
minimal risk of a security breach is the ultimate goal of SysAdm.
Welcome to SysAdm™! This documentation is intended to educate the user on initializing and managing the SysAdm™ middleware.
Initialization and management will be documented in two separate chapters, :ref:`gettingstarted`, and :ref:`management`.
API documentation is being handled at https://api.pcbsd.org.
Welcome to SysAdm™! This documentation is intended to educate the user
on initializing and managing the SysAdm™ middleware. Initialization and
management will be documented in two separate chapters,
:ref:`gettingstarted`, and :ref:`management`. API documentation is being
handled at https://api.pcbsd.org.

20
docs/manage.rst
View File

@@ -3,10 +3,12 @@
SysAdm™ Management
==================
SysAdm™ comes with a standard configuration file located at :file:`/usr/local/etc/sysadm.conf.dist`.
SysAdm™ comes with a standard configuration file located at
:file:`/usr/local/etc/sysadm.conf.dist`.
It is possible to edit this file for a custom configuration, but the result will need to be saved as :kbd:`sysadm.conf`.
Here is the current default settings for SysAdm™::
It is possible to edit this file for a custom configuration, but the
result will need to be saved as :kbd:`sysadm.conf`. Here are the current
default settings for SysAdm™::
#Sample Configuration file for the sysadm server
@@ -21,10 +23,14 @@ This default configuration also has blacklist options, recreated here::
### Blacklist options ###
# - Number of minutes that an IP remains on the blacklist
BLACKLIST_BLOCK_MINUTES=60
# - Number of authorization failures before an IP is placed on the blacklist
# - Number of authorization failures before an IP is placed on the
blacklist
BLACKLIST_AUTH_FAIL_LIMIT=5
# - Number of minutes of no activity from an IP before resetting the failure counter
# (Note: A successful authorization will always reset the fail counter)
# - Number of minutes of no activity from an IP before resetting the
failure counter
# (Note: A successful authorization will always reset the fail
counter)
BLACKLIST_AUTH_FAIL_RESET_MINUTES=10
Please note these default options are subject to change as the SysAdm™ utility is developed.
Please note these default options are subject to change as the SysAdm™
utility is developed.