diff --git a/docs/api_reference/classes/iocage.rst b/docs/api_reference/classes/iocage.rst index 6535034..51c9257 100644 --- a/docs/api_reference/classes/iocage.rst +++ b/docs/api_reference/classes/iocage.rst @@ -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) `_ +In this example, the **-e** switch, which creates an empty jail, is +specified using "switches". Refer to +`iocage(8) `_ for the list of available switches. **REST Request** @@ -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" - } + } \ No newline at end of file diff --git a/docs/api_reference/classes/iohyve.rst b/docs/api_reference/classes/iohyve.rst index d7ae60a..1c4466f 100644 --- a/docs/api_reference/classes/iohyve.rst +++ b/docs/api_reference/classes/iohyve.rst @@ -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 ` 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** diff --git a/docs/api_reference/classes/lifepreserver.rst b/docs/api_reference/classes/lifepreserver.rst index 5244eea..e58a587 100644 --- a/docs/api_reference/classes/lifepreserver.rst +++ b/docs/api_reference/classes/lifepreserver.rst @@ -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** diff --git a/docs/api_reference/classes/logs.rst b/docs/api_reference/classes/logs.rst index ede9e95..6f7ace3 100644 --- a/docs/api_reference/classes/logs.rst +++ b/docs/api_reference/classes/logs.rst @@ -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 `_. - -* **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 `_. + +* **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: diff --git a/docs/api_reference/classes/network.rst b/docs/api_reference/classes/network.rst index 5e039dc..579b144 100644 --- a/docs/api_reference/classes/network.rst +++ b/docs/api_reference/classes/network.rst @@ -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** diff --git a/docs/api_reference/classes/pkg.rst b/docs/api_reference/classes/pkg.rst index f771f9a..25fcd16 100644 --- a/docs/api_reference/classes/pkg.rst +++ b/docs/api_reference/classes/pkg.rst @@ -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: diff --git a/docs/api_reference/classes/systemmanager.rst b/docs/api_reference/classes/systemmanager.rst index caa3a8d..5144e25 100644 --- a/docs/api_reference/classes/systemmanager.rst +++ b/docs/api_reference/classes/systemmanager.rst @@ -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: diff --git a/docs/api_reference/classes/updates.rst b/docs/api_reference/classes/updates.rst index ba2c7a1..4d3573c 100644 --- a/docs/api_reference/classes/updates.rst +++ b/docs/api_reference/classes/updates.rst @@ -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" } } - } + } \ No newline at end of file diff --git a/docs/api_reference/classes/users.rst b/docs/api_reference/classes/users.rst index fff7cd0..171f14c 100644 --- a/docs/api_reference/classes/users.rst +++ b/docs/api_reference/classes/users.rst @@ -130,12 +130,12 @@ Group Modify required fields: "name": "", and any **one** of three choices: -* "users": [""] (will set the list of users for this - group). -* "add_users": [""] (will add the listed users to the - current users). -* "remove_users": [""] (will remove the listed users - from the current users). +* **users**: [""] Will set the list of users for this + group. +* **add_users**: [""] Will add the listed users to the + current users. +* **remove_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" - } + } \ No newline at end of file diff --git a/docs/api_reference/classes/zfs.rst b/docs/api_reference/classes/zfs.rst index 1998d71..9041dce 100644 --- a/docs/api_reference/classes/zfs.rst +++ b/docs/api_reference/classes/zfs.rst @@ -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**