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

Finish in-depth review of API Guide:

Browse Source 
- Line by line review of all .rst files in the API Reference Guide.
- Fix whitespace issues.
- Fix numerous spelling and grammar errors.
- Reworked numerous sections for clarity and flow.
- Fixed oversize tables to be fully PEP8 compliant.
This commit is contained in:
Mrt134
2016-08-25 13:42:30 -04:00
parent 7ec47963ac
commit 65037a300c
10 changed files with 538 additions and 522 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/api_reference/classes/iocage.rst
View File

@@ -1034,8 +1034,6 @@ 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.
.. TODO CONTINUE EDITING BELOW------------------------------------------
**REST Request**
::
@@ -1048,7 +1046,7 @@ the "release" property specifies which template to use.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"args" : {
@@ -1062,7 +1060,7 @@ the "release" property specifies which template to use.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1079,8 +1077,9 @@ the "release" property specifies which template to use.
"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>`_
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**
@@ -1096,7 +1095,7 @@ for the list of available switches.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "sysadm",
@@ -1127,7 +1126,7 @@ for the list of available switches.
"name": "response",
"namespace": "sysadm"
}
.. index:: destroyjail, iocage
.. _Destroy a Jail:
@@ -1135,8 +1134,8 @@ for the list 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
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**
@@ -1151,7 +1150,7 @@ jail is running.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"args" : {
@@ -1165,7 +1164,7 @@ jail is running.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1179,7 +1178,7 @@ jail is running.
"name": "response",
"namespace": "sysadm"
}
.. index:: execjail, iocage
.. _Run Command:
@@ -1187,9 +1186,9 @@ jail is running.
Run Command
===========
The "execjail" action executes the specified "command" under the
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
will indicate whether or not command execution succeeded as well as any
output from the command.
**REST Request**
@@ -1206,7 +1205,7 @@ output from the command.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "sysadm",
@@ -1222,7 +1221,7 @@ output from the command.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1236,7 +1235,7 @@ output from the command.
"name": "response",
"namespace": "sysadm"
}
.. index:: cleanjails, iocage
.. _Clean Jails:
@@ -1244,7 +1243,7 @@ output from the command.
Clean Jails
===========
The "cleanjails" action destroys all existing jail datasets, including
The "cleanjails" action destroys all existing jail datasets, including
all data stored in the jails.
**REST Request**
@@ -1258,7 +1257,7 @@ all data stored in the jails.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "sysadm",
@@ -1271,7 +1270,7 @@ all data stored in the jails.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1283,7 +1282,7 @@ all data stored in the jails.
"name": "response",
"namespace": "sysadm"
}
.. index:: cleanreleases, iocage
.. _Clean Releases:
@@ -1291,8 +1290,8 @@ all data stored in the jails.
Clean Releases
==============
The "cleanreleases" action deletes all releases that have been fetched.
Since basejails rely on releases, do not run this action if any
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**
@@ -1308,7 +1307,7 @@ basejails still exist.
**REST Request**
.. code-block:: json
.. code-block:: json
{
"id" : "fooid",
@@ -1323,7 +1322,7 @@ basejails still exist.
**REST Request**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1335,7 +1334,7 @@ basejails still exist.
"name": "response",
"namespace": "sysadm"
}
.. index:: cleantemplates, iocage
.. _Clean Templates:
@@ -1356,7 +1355,7 @@ The "cleantemplates" action destroys all existing jail templates.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"args" : {
@@ -1381,15 +1380,15 @@ The "cleantemplates" action destroys all existing jail templates.
"name": "response",
"namespace": "sysadm"
}
.. index:: cleanall, iocage
.. index:: cleanall, iocage
.. _Clean All:
Clean All
===========
=========
The "cleanall" action destroys everything associated with iocage.
The "cleanall" action destroys everything associated with iocage.
**REST Request**
@@ -1402,7 +1401,7 @@ The "cleanall" action destroys everything associated with iocage.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "sysadm",
@@ -1415,7 +1414,7 @@ The "cleanall" action destroys everything associated with iocage.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -1427,7 +1426,7 @@ The "cleanall" action destroys everything associated with iocage.
"name": "response",
"namespace": "sysadm"
}
.. index:: activatepool, iocage
.. _Activate a Pool:
@@ -1435,9 +1434,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 the ZFS pool to store
jails. If you do not specify the pool, the response will indicate the
current setting.
These examples specify the pool to use:
@@ -1546,19 +1545,19 @@ These examples show responses when the pool is not specified:
"name": "response",
"namespace": "sysadm"
}
.. index:: deactivatepool, iocage
.. index:: deactivatepool, iocage
.. _Deactivate a Pool:
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
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**
@@ -1610,4 +1609,4 @@ or activate the old pool again.
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
}

114
docs/api_reference/classes/iohyve.rst
View File

@@ -8,27 +8,29 @@ bhyve type 2 hypervisor.
Every iohyve class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | iohyve | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "listvms", "fetchiso", "listisos", "renameiso", "rmiso", "setup", "issetup", "create", |
| | | "install", "start", "stop", "delete", "adddisk", "listdisks", "resizedisk", "deletedisk", "version", "getprops", |
| | | and "setprop" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+================================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+------------------------------------------------+
| name | iohyve | |
| | | |
+---------------+-----------+------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+------------------------------------------------+
| action | | Actions include "adddisk", "create", |
| | | "delete", "deletedisk", "fetchiso", |
| | | "getprops", "install", "issetup", "listdisks", |
| | | "listisos", "listvms", "renameiso", |
| | | "resizedisk", "rmiso", "setprop", "setup", |
| | | "start", "stop", and "version" |
+---------------+-----------+------------------------------------------------+
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
@@ -37,10 +39,10 @@ for each type of request, along with their responses.
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
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**
@@ -101,7 +103,7 @@ loaded into memory.
"name": "response",
"namespace": "sysadm"
}
.. index:: fetchiso, iohyve
.. _Fetch ISO:
@@ -109,8 +111,8 @@ loaded into memory.
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
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**
@@ -191,7 +193,7 @@ The "listisos" action lists all the known ISO files which iohyve can use.
**REST Request**
::
PUT /sysadm/iohyve
{
"action" : "listisos"
@@ -200,7 +202,7 @@ The "listisos" action lists all the known ISO files which iohyve can use.
**WebSocket Request**
.. code-block:: json
{
"name" : "iohyve",
"namespace" : "sysadm",
@@ -213,7 +215,7 @@ The "listisos" action lists all the known ISO files which iohyve can use.
**Response**
.. code-block:: json
{
"args": {
"listisos": [
@@ -224,7 +226,7 @@ The "listisos" action lists all the known ISO files which iohyve can use.
"name": "response",
"namespace": "sysadm"
}
.. index:: renameiso, iohyve
.. _Rename ISO:
@@ -276,7 +278,7 @@ Specify the existing name with "source" and the new name with "target".
"name": "response",
"namespace": "sysadm"
}
.. index:: rmiso, iohyve
.. _Remove ISO:
@@ -284,7 +286,7 @@ Specify the existing name with "source" and the new name with "target".
Remove ISO
==========
The "rmiso" action is used to to remove an existing ISO file from disk.
The "rmiso" action is used to to remove an existing ISO file from disk.
Specify the ISO's name as the "target".
**REST Request**
@@ -325,7 +327,7 @@ Specify the ISO's name as the "target".
"name": "response",
"namespace": "sysadm"
}
.. index:: setup, iohyve
.. _Setup iohyve:
@@ -334,7 +336,7 @@ 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
to specify the FreeBSD device name of the "nic" and the ZFS "pool" to
use.
**REST Request**
@@ -378,7 +380,7 @@ use.
"name": "response",
"namespace": "sysadm"
}
.. index:: issetup, iohyve
.. _Determine iohyve Setup:
@@ -425,7 +427,7 @@ The "issetup" action queries if iohyve has been setup and returns either
"name": "response",
"namespace": "sysadm"
}
.. index:: create, iohyve
.. _Create Guest:
@@ -477,7 +479,7 @@ and "size".
"name": "response",
"namespace": "sysadm"
}
.. index:: install, iohyve
.. _Install Guest:
@@ -485,7 +487,7 @@ and "size".
Install Guest
=============
The "install" action starts the iohyve installation of the specified
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.
@@ -531,7 +533,7 @@ the system.
"name": "response",
"namespace": "sysadm"
}
.. index:: start, iohyve
.. _Start VM:
@@ -579,7 +581,7 @@ The "start" action starts the specified VM.
"name": "response",
"namespace": "sysadm"
}
.. index:: stop, iohyve
.. _Stop VM:
@@ -627,7 +629,7 @@ The "stop" action stops the specified VM.
"name": "response",
"namespace": "sysadm"
}
.. index:: delete, iohyve
.. _Delete a VM:
@@ -675,7 +677,7 @@ The "delete" action deletes the specified iohyve guest.
"name": "response",
"namespace": "sysadm"
}
.. index:: adddisk, iohyve
.. _Add a Disk:
@@ -727,7 +729,7 @@ The "adddisk" action adds and creates a disk for a VM.
"name": "response",
"namespace": "sysadm"
}
.. index:: listdisks, iohyve
.. _List Disks:
@@ -775,7 +777,7 @@ The "listdisks" action lists the disks connected to the specified VM.
"name": "response",
"namespace": "sysadm"
}
.. index:: resizedisk, iohyve
.. _Resize a Disk:
@@ -783,8 +785,8 @@ 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
The "resizedisk" action **increases** the specified disk in the
specified VM. The new specified size must be larger than the current
size.
**REST Request**
@@ -801,7 +803,7 @@ size.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"name" : "iohyve",
@@ -817,7 +819,7 @@ size.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -831,7 +833,7 @@ size.
"name": "response",
"namespace": "sysadm"
}
.. index:: deletedisk, iohyve
.. _Delete a Disk:
@@ -882,7 +884,7 @@ The "deletedisk" action removes the specified disk from the specified VM.
"name": "response",
"namespace": "sysadm"
}
.. index:: version, iohyve
.. _List Version:
@@ -928,7 +930,7 @@ The "version" action displays the iohyve version.
"name": "response",
"namespace": "sysadm"
}
.. index:: getprops, iohyve
.. _List Guest Properties:
@@ -991,16 +993,16 @@ The "getprops" action lists the properties for the specified guest.
"name": "response",
"namespace": "sysadm"
}
.. index:: setprop, iohyve
.. _Set Guest Properties:
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.
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**

341
docs/api_reference/classes/lifepreserver.rst
View File

@@ -8,26 +8,29 @@ scheduled snapshots and replication.
Every lifepreserver class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | lifepreserver | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "listcron", "cronsnap", "cronscrub", "createsnap", "listsnap", "revertsnap", "removesnap", |
| | | "addreplication", "removereplication", "listreplication", "runreplication", "initreplication", "settings", and |
| | | "savesettings" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+---------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===============+=======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+---------------+---------------------------------------+
| name | lifepreserver | |
| | | |
+---------------+---------------+---------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+---------------+---------------------------------------+
| action | | Actions include "addreplication", |
| | | "createsnap", "cronscrub", "cronsnap" |
| | | "initreplication", "listcron", |
| | | "listreplication", "listsnap", |
| | | "removesnap", "removereplication", |
| | | "revertsnap", "runreplication", |
| | | "savesettings", and "settings" |
+---------------+---------------+---------------------------------------+
The rest of this section provides examples of the available *actions*
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listcron, Life Preserver
@@ -37,10 +40,10 @@ for each type of request, along with their responses.
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 "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**
@@ -52,7 +55,6 @@ the time that ZFS scrubs occur.
"action" : "listcron"
}
**REST Response**
.. code-block:: json
@@ -68,7 +70,7 @@ the time that ZFS scrubs occur.
}
}
}
**WebSocket Request**
.. code-block:: json
@@ -102,30 +104,30 @@ the time that ZFS scrubs occur.
}
.. index:: cronsnap, Life Preserver
.. _Create a Snapshot Schedule:
Create a Snapshot Schedule
==========================
The "cronsnap" action is used to create snapshot schedules for Life
The "cronsnap" action is used to create snapshot schedules for Life
Preserver. This action supports the following parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| pool | name of ZFS pool to snapshot |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| keep | specify the number of snapshots to keep |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| frequency | specify when to take the snapshots; possible values are "daily@XX" (where XX is the number of the hour), |
| | "hourly", "30min", "10min", "5min" or "none" (disables snapshots) |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+======================================================+
| pool | Name of the ZFS pool to snapshot. |
| | |
+---------------+------------------------------------------------------+
| keep | Specify the number of snapshots to keep. |
| | |
+---------------+------------------------------------------------------+
| frequency | Specify when to take the snapshots. Possible values |
| | are "daily@XX" (where XX is the number of the hour), |
| | "hourly", "30min", "10min", "5min" or "none" |
| | (disables snapshots) |
+---------------+------------------------------------------------------+
**REST Request**
@@ -185,29 +187,31 @@ Preserver. This action supports the following parameters:
"name": "response",
"namespace": "sysadm"
}
.. index:: cronscrub, Life Preserver
.. _Create a Scrub Schedule:
Create a Scrub Schedule
==========================
=======================
The "cronscrub" action is used to schedule a ZFS scrub. This action
The "cronscrub" action is used to schedule a ZFS scrub. This action
supports the following parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| pool | name of ZFS pool to scrub |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| frequency | specify when to perform the scrub; possible values are "daily@XX", "weekly@YY@XX", and monthly@ZZ@XX, where "XX" is |
| | the hour, "YY" is the day of week ("01" for Monday through "07" for Sunday), "ZZ" is the day of month, and "none" |
| | disables scrubs |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+----------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+====================================================+
| pool | Name of ZFS pool to scrub. |
| | |
+---------------+----------------------------------------------------+
| frequency | Specify when to perform the scrub. Possible values |
| | are "daily@XX", "weekly@YY@XX", and monthly@ZZ@XX, |
| | where "XX" is the hour, "YY" is the day of week |
| | ("01" for Monday through "07" for Sunday), "ZZ" is |
| | the day of month, and "none"disables scrubs. |
| | |
+---------------+----------------------------------------------------+
**REST Request**
@@ -263,15 +267,15 @@ supports the following parameters:
"name": "response",
"namespace": "sysadm"
}
.. index:: createsnap, Life Preserver
.. _Create a Snapshot:
Create a Snapshot
=================
The "createsnap" action creates a one-time snapshot of the specified
The "createsnap" action creates a one-time snapshot of the specified
dataset.
**REST Request**
@@ -288,7 +292,7 @@ dataset.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"args" : {
@@ -304,7 +308,7 @@ dataset.
**Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -320,7 +324,7 @@ dataset.
}
.. index:: listsnap, Life Preserver
.. _List Snapshots:
List Snapshots
@@ -402,20 +406,20 @@ The "listsnap" action retrieves the list of saved snapshots.
}
.. index:: revertsnap, Life Preserver
.. _Revert a Snapshot:
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
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.
.. danger:: 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**
@@ -473,13 +477,13 @@ taken.
}
.. index:: removesnap, Life Preserver
.. _Remove a Snapshot:
Remove a Snapshot
=================
The "removesnap" action is used to remove a ZFS snapshot from the
The "removesnap" action is used to remove a ZFS snapshot from the
specified dataset or pool.
**REST Request**
@@ -538,42 +542,44 @@ specified dataset or pool.
}
.. index:: addreplication, Life Preserver
.. _Add Replication:
Add Replication
===============
The "addreplication" action is used to create a replication task in Life
Preserver. This action supports the following parameters:
Preserver. This action supports several parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| host | remote hostname or IP address |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| port | SSH port number on remote system |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| user | user must exist on remote system |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| password | the password for *user* on remote system |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| dataset | name of local dataset to replicate |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| remotedataset | path to dataset on remote system |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| frequency | when to replicate; supported times are "XX" (hour), "sync" (as snapshot is created, not recommended for frequent |
| | snapshots), "hour" (hourly), "30min" (every 30 minutes), "10min" (every 10 minutes), or "manual" (only when |
| | requested by user) |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+=====================================================+
| host | Remote hostname or IP address. |
| | |
+---------------+-----------------------------------------------------+
| port | SSH port number on remote system. |
| | |
+---------------+-----------------------------------------------------+
| user | User must exist on remote system. |
| | |
+---------------+-----------------------------------------------------+
| password | The password for *user* on remote system. |
| | |
+---------------+-----------------------------------------------------+
| dataset | Name of local dataset to replicate. |
| | |
+---------------+-----------------------------------------------------+
| remotedataset | Path to the dataset on the remote system. |
| | |
+---------------+-----------------------------------------------------+
| frequency | When to replicate. Supported times are "XX" (hour), |
| | "sync" (as snapshot is created, not recommended for |
| | frequent snapshots), "hour" (hourly), "30min" |
| | (every 30 minutes), "10min" (every 10 minutes), or |
| | "manual" (only when requested by user) |
| | |
+---------------+-----------------------------------------------------+
**REST Request**
@@ -649,28 +655,28 @@ Preserver. This action supports the following parameters:
}
.. index:: removereplication, Life Preserver
.. _Remove Replication:
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
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:
This action supports several parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| host | remote hostname or IP address |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| dataset | name of local dataset to remove from replication |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+=====================================================+
| host | Remote hostname or IP address. |
| | |
+---------------+-----------------------------------------------------+
| dataset | Name of local dataset to remove from replication. |
| | |
+---------------+-----------------------------------------------------+
**REST Request**
@@ -728,19 +734,19 @@ This action supports the following parameters:
}
.. index:: listreplication, Life Preserver
.. _List Replications:
.. _List Replications:
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
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
store the replicated data ("rdset"), and the name of the replication
user account.
**REST Request**
@@ -805,15 +811,15 @@ user account.
"name": "response",
"namespace": "sysadm"
}
.. index:: runreplication, Life Preserver
.. _Start Replication:
Start Replication
=================
The "runreplication" action can be used to manually replicate the
The "runreplication" action can be used to manually replicate the
specified dataset to the specified remote server.
**REST Request**
@@ -870,31 +876,31 @@ specified dataset to the specified remote server.
"name": "response",
"namespace": "sysadm"
}
.. index:: initreplication, Life Preserver
.. _Initialize Replication:
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
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:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| host | remote hostname or IP address |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| dataset | name of local dataset or pool being replicated |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+=====================================================+
| host | Remote hostname or IP address. |
| | |
+---------------+-----------------------------------------------------+
| dataset | Name of local dataset or pool being replicated. |
| | |
+---------------+-----------------------------------------------------+
**REST Request**
@@ -950,22 +956,22 @@ The "initreplication" action supports the following parameters:
"name": "response",
"namespace": "sysadm"
}
.. index:: settings, Life Preserver
.. _View Settings:
View Settings
=============
The "settings" action returns the system-wide settings of the Life
Preserver utility. The returned settings include the disk percentage
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
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
Run :command:`lpreserver help set` for more information about each
available setting.
**REST Request**
@@ -1024,33 +1030,34 @@ available setting.
}
.. index:: savesettings, Life Preserver
.. _Save Settings:
Save Settings
=============
The "savesettings" action can be used to modify the system-wide settings
of the Life Preserver utility. This action supports the following
of the Life Preserver utility. This action supports the following
parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
| | |
+=================================+======================================================================================================================+
| duwarn | disk percentage (from 0-99) at which to warn of low disk space |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| email | email address to send notifications to |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| emailopts | conditions which trigger an email notification; possible values are "ALL" (every snapshot, warning and error), |
| | "WARN" (warnings and errors--this is the default condition), or "ERROR" (errors only) |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| recursive | whether or not to include all child datasets in the snapshot; possible values are "true" or "false" |
| | |
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------------------------------------------------+
| **Parameter** | **Description** |
| | |
+===============+=====================================================+
| duwarn | Disk percentage (from 0-99) at which to warn of low |
| | disk space. |
+---------------+-----------------------------------------------------+
| email | Email address to send notifications. |
| | |
+---------------+-----------------------------------------------------+
| emailopts | Conditions which trigger an email notification. |
| | Possible values are "ALL" (every snapshot, warning |
| | and error),"WARN" (warnings and errors--this is the |
| | default condition), or "ERROR" (errors only). |
+---------------+-----------------------------------------------------+
| recursive | Whether or not to include all child datasets in the |
| | snapshot; possible values are "true" or "false" |
+---------------+-----------------------------------------------------+
**REST Request**

61
docs/api_reference/classes/logs.rst
View File

@@ -3,30 +3,30 @@
logs
****
The logs class is used to interact with the log files created by the
The logs class is used to interact with the log files created by the
SysAdm™ server.
Every logs class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | logs | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | rpc | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "read_logs" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+-----------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+=========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+-----------------------------------------+
| name | logs | |
| | | |
+---------------+-----------+-----------------------------------------+
| namespace | rpc | |
| | | |
+---------------+-----------+-----------------------------------------+
| action | | Supported actions include "read_logs". |
| | | |
+---------------+-----------+-----------------------------------------+
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
@@ -35,28 +35,29 @@ for each type of request, along with their responses.
Read Logs
=========
The "read_logs" action can be used to display log entries. It supports
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
* **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>`_.
* **start_time:** displays log entries that occurred after the time
* **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".
* **end_time:** displays log entries that occurred before the time
* **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
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
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:

48
docs/api_reference/classes/network.rst
View File

@@ -3,30 +3,30 @@
network
*******
The network class is used to manage and retrieve information from
The network class is used to manage and retrieve information from
Ethernet and wireless network devices.
Every network class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | network | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "list-devices" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+-------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+===========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+-------------------------------------------+
| name | network | |
| | | |
+---------------+-----------+-------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+-------------------------------------------+
| action | | Supported actions include "list-devices". |
| | | |
+---------------+-----------+-------------------------------------------+
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
@@ -35,11 +35,11 @@ for each type of request, along with their responses.
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
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**

175
docs/api_reference/classes/pkg.rst
View File

@@ -5,28 +5,33 @@ pkg
The pkg class is used to manage software packages.
Every pkg class request contains the following parameters:
Every pkg class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | pkg | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "pkg_info", "pkg_search", "list_categories", "list_repos", "pkg_audit", "pkg_upgrade", |
| | | "pkg_check_upgrade", "pkg_update", "pkg_lock", "pkg_unlock", "pkg_install", "pkg_remove", and "pkg_autoremove" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+-------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+===========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+-------------------------------------------+
| name | pkg | |
| | | |
+---------------+-----------+-------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+-------------------------------------------+
| action | | Supported actions include |
| | | "list_categories", "list_repos", |
| | | "pkg_audit", "pkg_autoremove", |
| | | "pkg_check_upgrade", "pkg_info", |
| | | "pkg_install", "pkg_lock", "pkg_remove", |
| | | "pkg_search", "pkg_unlock", "pkg_update", |
| | | and "pkg_upgrade" |
| | | |
+---------------+-----------+-------------------------------------------+
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
@@ -35,19 +40,19 @@ for each type of request, along with their responses.
Package Information
===================
The "pkg_info" action reads the pkg database directly and returns any
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.
* **"repo"**: Unless specified, defaults to the local package repository.
* **"pkg_origins"**: unless specified, information for all installed
* **"pkg_origins"**: Unless specified, information for all installed
packages will be listed.
* **"category"**: limits the results to packages within the specified
* **"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
* **"result"**: Must be set to "full" to retrieve all of the information
with multiple possible values, such as "dependencies", "options", and
"licences".
**REST Request**
@@ -162,20 +167,20 @@ relevant information. The following arguments are optional:
"namespace": "sysadm"
}
.. index:: pkg_search, pkg
.. index:: pkg_search, pkg
.. _Search Packages:
Search Packages
===============
The "pkg_search" action searches the package database for pkgs which
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.
* **"repo"**: May be used to specify searching the specified repository.
If not specified, the local package database is searched.
* **"category"**: may be used to restrict searches to the specified
* **"category"**: May be used to restrict searches to the specified
package category.
**REST Request**
@@ -353,8 +358,8 @@ match the given "search_term" (required). These parameters are optional:
List Categories
===============
The "list_categories" action lists all the known, non-empty categories
within the specified repository or, if no repository is specified, the
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**
@@ -370,7 +375,7 @@ local repository.
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"args" : {
@@ -384,7 +389,7 @@ local repository.
**Response**
.. code-block:: json
{
"args": {
"list_categories": [
@@ -454,9 +459,9 @@ local repository.
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"
The "list_repositories" action scans 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**
@@ -504,15 +509,15 @@ 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
.. 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
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**
@@ -576,7 +581,7 @@ packages which are impacted by those vulnerabilities.
"state" : "finished"
}
}
}
}
.. index:: pkg_upgrade, pkg
@@ -585,9 +590,9 @@ packages which are impacted by those vulnerabilities.
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
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**
@@ -660,9 +665,9 @@ 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
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**
@@ -703,7 +708,7 @@ subscribe to and query dispatcher events.
"name": "response",
"namespace": "sysadm"
}
**Dispatcher Events System Reply**
.. code-block:: json
@@ -737,12 +742,12 @@ 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
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
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**
@@ -785,7 +790,7 @@ some time.
"name": "response",
"namespace": "sysadm"
}
**Dispatcher Events System Reply**
.. code-block:: json
@@ -808,25 +813,25 @@ some time.
"state" : "finished"
}
}
}
}
.. index:: pkg_lock, pkg_unlock, pkg
.. _Lock/Unlock Packages:
.. _LockUnlock Packages:
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
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
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**
@@ -896,8 +901,8 @@ query dispatcher events.
"state" : "finished"
}
}
}
}
**REST Request**
::
@@ -938,7 +943,7 @@ query dispatcher events.
"name": "response",
"namespace": "sysadm"
}
**Dispatcher Events System Reply**
.. code-block:: json
@@ -961,8 +966,8 @@ query dispatcher events.
"state" : "finished"
}
}
}
}
.. index:: pkg_install, pkg
.. _Install Packages:
@@ -970,12 +975,12 @@ query dispatcher events.
Install Packages
================
The "pkg_install" action installs the specified "pkg_origins" on the
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
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
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and
query dispatcher events.
**REST Request**
@@ -1043,8 +1048,8 @@ query dispatcher events.
"state" : "finished"
}
}
}
}
.. index:: pkg_remove, pkg
.. _Uninstall Packages:
@@ -1052,16 +1057,16 @@ query dispatcher events.
Uninstall Packages
==================
The "pkg_remove" action uninstalls the specified "pkg_origins" from the
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
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
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**
@@ -1106,7 +1111,7 @@ and query dispatcher events.
"name": "response",
"namespace": "sysadm"
}
**Dispatcher Events System Reply**
.. code-block:: json
@@ -1129,8 +1134,8 @@ and query dispatcher events.
"state" : "finished"
}
}
}
}
.. index:: pkg_autoremove, pkg
.. _Prune Packages:

117
docs/api_reference/classes/systemmanager.rst
View File

@@ -4,27 +4,30 @@ systemmanager
*************
The systemmanager class is used to retrieve information about the system.
Every systemmanager class request contains the following parameters:
Every systemmanager class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | systemmanager | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "memorystats", "cpupercentage", "cputemps", "procinfo", "killproc", "batteryinfo", |
| | | "externalmounts", "systemmanager", "sysctllist", "setsysctl", "halt", and "reboot" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+---------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===============+=======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+---------------+---------------------------------------+
| name | systemmanager | |
| | | |
+---------------+---------------+---------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+---------------+---------------------------------------+
| action | | Actions include "batteryinfo", |
| | | "cpupercentage", "cputemps", |
| | | "externalmounts", "halt", "killproc", |
| | | "memorystats", "procinfo", "reboot", |
| | | "setsysctl", "sysctllist", and |
| | | "systemmanager" |
+---------------+---------------+---------------------------------------+
The rest of this section provides examples of the available *actions*
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: memorystats, systemmanager
@@ -114,7 +117,7 @@ The "cpupercentage" action returns the usage percentage of each CPU.
**REST Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -151,7 +154,7 @@ The "cpupercentage" action returns the usage percentage of each CPU.
**WebSocket Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -175,7 +178,7 @@ The "cpupercentage" action returns the usage percentage of each CPU.
"name": "response",
"namespace": "sysadm"
}
.. index:: cputemps, systemmanager
.. _CPU Temperature:
@@ -196,7 +199,7 @@ The "cputemps" action returns the temperature of each CPU.
**REST Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -211,7 +214,7 @@ The "cputemps" action returns the temperature of each CPU.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"args" : {
@@ -224,7 +227,7 @@ The "cputemps" action returns the temperature of each CPU.
**WebSocket Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -239,7 +242,7 @@ The "cputemps" action returns the temperature of each CPU.
"name": "response",
"namespace": "sysadm"
}
.. index:: procinfo, systemmanager
.. _Process Information:
@@ -247,9 +250,9 @@ 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
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**
@@ -263,7 +266,7 @@ listed by this action.
**REST Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -287,7 +290,7 @@ listed by this action.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"id" : "fooid",
@@ -300,7 +303,7 @@ listed by this action.
**WebSocket Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -323,16 +326,16 @@ listed by this action.
"name": "response",
"namespace": "sysadm"
}
.. index:: killproc, systemmanager
.. index:: killproc, systemmanager
.. _Kill a Process:
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,
The "killproc" action can be used to send a specified signal to the
specified Process ID (PID). The following signals are supported: INT,
QUIT, ABRT, KILL, ALRM, or TERM.
**REST Request**
@@ -348,7 +351,7 @@ QUIT, ABRT, KILL, ALRM, or TERM.
**REST Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -362,7 +365,7 @@ QUIT, ABRT, KILL, ALRM, or TERM.
**WebSocket Request**
.. code-block:: json
.. code-block:: json
{
"namespace" : "sysadm",
@@ -377,7 +380,7 @@ QUIT, ABRT, KILL, ALRM, or TERM.
**WebSocket Response**
.. code-block:: json
.. code-block:: json
{
"args": {
@@ -391,7 +394,7 @@ QUIT, ABRT, KILL, ALRM, or TERM.
"name": "response",
"namespace": "sysadm"
}
.. index:: batteryinfo, systemmanager
.. _Battery Information:
@@ -399,9 +402,9 @@ QUIT, ABRT, KILL, ALRM, or TERM.
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
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**
@@ -460,9 +463,9 @@ estimated time left (in seconds).
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
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**
@@ -529,9 +532,9 @@ device name, filesystem, mount path, and device type.
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
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**
@@ -598,7 +601,7 @@ system's uptime.
"name": "response",
"namespace": "sysadm"
}
.. index:: sysctllist, systemmanager
.. _List Sysctls:
@@ -606,9 +609,9 @@ 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 configurable
sysctl values. Since there are many, the example responses in this
section have been truncated.
**REST Request**
@@ -674,7 +677,7 @@ been truncated to just show a few.
"name": "response",
"namespace": "sysadm"
}
.. index:: setsysctl, systemmanager
.. _Set a Sysctl:
@@ -682,8 +685,8 @@ been truncated to just show a few.
Set a Sysctl
============
The "setsysctl" action sets the specified setable sysctl to the
specified value. The response indicates that the old value was changed
The "setsysctl" action sets the specified configurable sysctl to the
specified value. The response indicates that the old value was changed
to the new value.
**REST Request**
@@ -742,7 +745,7 @@ to the new value.
"name": "response",
"namespace": "sysadm"
}
.. index:: halt, systemmanager
.. _Halt the System:

49
docs/api_reference/classes/updates.rst
View File

@@ -3,18 +3,17 @@
update
******
The update class is used to check for and manage system and software
The update class is used to check for and manage system and software
updates.
Every update class request contains the following parameters:
Every update class request contains several parameters:
+----------------+------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+================+============+=======================================+
| id | | any unique value for the request; |
| | | examples include a hash, checksum, or |
| | | uuid |
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+----------------+------------+---------------------------------------+
| name | update | |
| | | |
@@ -22,14 +21,14 @@ Every update class request contains the following parameters:
| namespace | sysadm | |
| | | |
+----------------+------------+---------------------------------------+
| action | | supported actions include |
| | | "changesettings", "checkupdates", |
| | | "listbranches", "listsettings", |
| | | "startupdate", "stopupdate" |
| action | | Actions include "changesettings", |
| | | "checkupdates", "listbranches", |
| | | "listsettings", "startupdate", |
| | | "stopupdate" |
+----------------+------------+---------------------------------------+
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:: changesettings, update
@@ -87,10 +86,10 @@ settings (maxbe, package_set, package_url, auto_update).
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
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**
@@ -144,7 +143,7 @@ installed software packages.
"name": "response",
"namespace": "sysadm"
}
.. index:: listbranches, update
.. _List Branches:
@@ -152,8 +151,8 @@ installed software packages.
List Branches
=============
The "listbranches" action retrieves the list of available branches
(operating system versions). The currently installed version will be
The "listbranches" action retrieves the list of available branches
(operating system versions). The currently installed version will be
listed as "active".
**REST Request**
@@ -262,17 +261,17 @@ Start Updates
=============
The "startupdate" action starts the specified update. You must specify a
"target" to indicate the type of update to perform. The available
"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
* **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.
* **pkgupdate:** Only updates installed software.
* **standalone:** only apply the update specified as a "tag". Use the
"checkupdates" action to determine the name (tag) of the update to
* **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**
@@ -386,4 +385,4 @@ and kill/stop them as needed.
"result": "success"
}
}
}
}

14
docs/api_reference/classes/users.rst
View File

@@ -130,12 +130,12 @@ Group Modify
required fields: "name": "<desired group>", and any **one** of three
choices:
* "users": ["<array of users>"] (will set the list of users for this
group).
* "add_users": ["<array of users>"] (will add the listed users to the
current users).
* "remove_users": ["<array of users>"] (will remove the listed users
from the current users).
* **users**: ["<array of users>"] Will set the list of users for this
group.
* **add_users**: ["<array of users>"] Will add the listed users to the
current users.
* **remove_users**: ["<array of users>"] Will remove the listed users
from the current users.
**REST Request**
@@ -553,4 +553,4 @@ system, regardless of active/inactive status.
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
}

50
docs/api_reference/classes/zfs.rst
View File

@@ -5,27 +5,27 @@ zfs
The zfs class is used to manage and retrieve information about ZFS pools.
Every zfs class request contains the following parameters:
Every zfs class request contains several 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, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+-------------------------------------------+
| name | zfs | |
| | | |
+---------------+-----------+-------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+-------------------------------------------+
| action | | 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
@@ -34,13 +34,13 @@ for each type of request, along with their responses.
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
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
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**