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

Begin in-depth review of API Reference guide.

Browse Source 
- Whitespace fixes.
- Reworking text.
- Reducing the size of tables for better PEP8 conformity.
- Altering admonition box titles (use tip and danger).
- Update roles (use :guilabel: and verify other uses).
This commit is contained in:
Mrt134
2016-08-24 15:57:57 -04:00
parent cf4a485382
commit 7ec47963ac
6 changed files with 380 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/api_reference/classes/beadm.rst
View File

@@ -7,25 +7,26 @@ The beadm class is used to manage boot environments.
Every beadm class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | beadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "listbes", "renamebe", "activatebe", "createbe", "destroybe", "mountbe", and "umountbe" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+----------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+========================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+----------------------------------------+
| name | beadm | |
| | | |
+---------------+-----------+----------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+----------------------------------------+
| action | | Supported actions include "listbes", |
| | | "renamebe", "activatebe", "createbe", |
| | | "destroybe", "mountbe", and "umountbe" |
+---------------+-----------+----------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listbes, beadm
@@ -34,12 +35,11 @@ for each type of request, along with their responses.
List Boot Environments
======================
The "listbes" action retrieves the list of boot environments. For each
boot environment, the response includes its name, its flags (where "R"
The "listbes" action retrieves the list of boot environments. For each
boot environment, the response includes its name, its flags (where "R"
is active on reboot, "N" is active now and "-" is inactive), the date it
was created, its mount point, its nickname, and its size.
**REST Request**
::
@@ -89,7 +89,7 @@ was created, its mount point, its nickname, and its size.
"name": "response",
"namespace": "sysadm"
}
.. index:: renamebe, beadm
.. _Rename a Boot Environment:
@@ -98,10 +98,9 @@ Rename a Boot Environment
=========================
The "renamebe" action renames the specified boot environment. When using
this action, specify the new name as the "source" and the boot
this action, specify the new name as the "source" and the boot
environment as the "target".
**REST Request**
::
@@ -143,7 +142,7 @@ environment as the "target".
"name": "response",
"namespace": "sysadm"
}
.. index:: activatebe, beadm
.. _Activate Boot Environment:
@@ -151,10 +150,9 @@ environment as the "target".
Activate Boot Environment
=========================
The "activatebe" action activates the specified boot environment
The "activatebe" action activates the specified boot environment
(target) so that it will be the default at next boot.
**REST Request**
::
@@ -193,7 +191,7 @@ The "activatebe" action activates the specified boot environment
"name": "response",
"namespace": "sysadm"
}
.. index:: createbe, beadm
.. _Create Boot Environment:
@@ -201,9 +199,9 @@ The "activatebe" action activates the specified boot environment
Create Boot Environment
=======================
The "create" action creates a new boot environment. Specify the name of
the boot environment as the "newbe". By default, this action clones the
active boot environment. To specify another, inactive boot environment,
The "create" action creates a new boot environment. Specify the name of
the boot environment as the "newbe". By default, this action clones the
active boot environment. To specify another, inactive boot environment,
also include "clonefrom" to specify which boot environment to clone from.
**REST Request**
@@ -247,7 +245,7 @@ also include "clonefrom" to specify which boot environment to clone from.
"name": "response",
"namespace": "sysadm"
}
.. index:: destroybe, beadm
.. _Destroy a Boot Environment:
@@ -255,10 +253,9 @@ also include "clonefrom" to specify which boot environment to clone from.
Destroy a Boot Environment
==========================
The "destroybe" action destroys the specified "target" boot environment
The "destroybe" action destroys the specified "target" boot environment
and forcefully unmounts it.
**REST Request**
::
@@ -297,7 +294,7 @@ and forcefully unmounts it.
"name": "response",
"namespace": "sysadm"
}
.. index:: mountbe, beadm
.. _Mount a Boot Environment:
@@ -305,7 +302,7 @@ and forcefully unmounts it.
Mount a Boot Environment
========================
The "mountbe" action mounts the specified boot environment. Use the
The "mountbe" action mounts the specified boot environment. Use the
optional "mountpoint" argument to specify the mount point.
**REST Request**
@@ -349,7 +346,7 @@ optional "mountpoint" argument to specify the mount point.
"name": "response",
"namespace": "sysadm"
}
.. index:: umountbe, beadm
.. _Unmount a Boot Environment:
@@ -357,7 +354,7 @@ optional "mountpoint" argument to specify the mount point.
Unmount a Boot Environment
==========================
The "umountbe" action forcibly unmounts the specified boot environment,
The "umountbe" action forcibly unmounts the specified boot environment,
even if it is in use.
**REST Request**

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

@@ -3,30 +3,30 @@
dispatcher
**********
The dispatcher class is used to spin up external processes on demand,
The dispatcher class is used to spin up external processes on demand,
such as a user running a custom system setup script.
Every dispatcher class request contains the following parameters:
Every dispatcher class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | dispatcher | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | rpc | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "list", "kill" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+------------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+============+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+------------+--------------------------------------+
| name | dispatcher | |
| | | |
+---------------+------------+--------------------------------------+
| namespace | rpc | |
| | | |
+---------------+------------+--------------------------------------+
| action | | Actions include "list" and "kill". |
| | | |
+---------------+------------+--------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list, dispatcher
@@ -35,8 +35,8 @@ for each type of request, along with their responses.
List Processes
==============
The "list" action lists all the currently running or pending processes
within the dispatcher queues. Possible queues are "no_queue",
The "list" action lists all the currently running or pending processes
within the dispatcher queues. Possible queues are "no_queue",
"pkg_queue", and "iocage_queue".
**REST Request**
@@ -83,7 +83,7 @@ within the dispatcher queues. Possible queues are "no_queue",
"name": "response",
"namespace": "rpc"
}
.. index:: kill, dispatcher
.. _Kill Processes:
@@ -91,7 +91,7 @@ within the dispatcher queues. Possible queues are "no_queue",
Kill Processes
==============
The "kill" action allows a user with full access to cancel pending or
The "kill" action allows a user with full access to cancel pending or
running jobs within the dispatcher system.
**REST Request**

38
docs/api_reference/classes/fs.rst
View File

@@ -5,27 +5,27 @@ fs
The fs class is used to manage the files and directories on the system.
Every fs class request contains the following parameters:
Every fs class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | fs | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "dirlist" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+--------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+======================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+--------------------------------------+
| name | fs | |
| | | |
+---------------+-----------+--------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+--------------------------------------+
| action | | Actions include "dirlist". |
| | | |
+---------------+-----------+--------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: dirlist, fs

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

@@ -3,33 +3,35 @@
iocage
******
The iocage class is used to manage jails which provide a light-weight,
operating system-level virtualization for running applications or
The iocage class is used to manage jails, which provide a light-weight,
operating system-level virtualization for running applications or
services.
Every iocage class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | iocage | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "getdefaultsettings", "listjails", "getjailsettings", "df", "startjail", "stopjail", |
| | | "capjail", "clonejail", "createjail", "destroyjail", "execjail", "cleanjails", "cleanreleases", "cleantemplates", |
| | | "cleanall", "activatepool", and "deactivatepool" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------+-----------+------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+===============+===========+======================================================+
| id | | Any unique value for the request, |
| | | including a hash, checksum, or uuid. |
+---------------+-----------+------------------------------------------------------+
| name | iocage | |
| | | |
+---------------+-----------+------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------+-----------+------------------------------------------------------+
| action | | Actions include "activatepool", "capjail", |
| | | "cleanall", "cleanjails", "cleanreleases", |
| | | "cleantemplates", "clonejail", "createjail", |
| | | "deactivatepool", "destroyjail", "df", |
| | | "execjail", "getdefaultsettings", "getjailsettings", |
| | | "listjails", "startjail", and "stopjail". |
+---------------+-----------+------------------------------------------------------+
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: getdefaultsettings, iocage
@@ -38,7 +40,7 @@ for each type of request, along with their responses.
Default Settings
================
The "getdefaultsettings" action lists all of the global settings that
The "getdefaultsettings" action lists all of the global settings that
apply to all jails.
**REST Request**
@@ -318,10 +320,10 @@ List Jails
==========
The "listjails" action lists information about currently installed jails.
For each jail, the response includes the UUID of the jail, whether or
not the jail has been configured to start at system boot, the jail ID
(only applies to running jails), whether or not the jail is running, a
friendly name for the jail (tag), and the type of jail (basejail or
For each jail, the response includes the UUID of the jail, whether or
not the jail has been configured to start at system boot, the jail ID
(only applies to running jails), whether or not the jail is running, a
friendly name for the jail (tag), and the type of jail (basejail or
thickjail).
**REST Request**
@@ -394,16 +396,16 @@ thickjail).
Jail Settings
=============
The "getjailsettings" action lists settings that apply to the specified
The "getjailsettings" action lists settings that apply to the specified
jail. This action supports 4 modes:
* specify a property and a jail
* Specify a property and a jail.
* specify a property and *-r* for all downloaded releases
* Specify a property and *-r* for all downloaded releases.
* specify *all* properties for the specified jail
* Specify *all* properties for the specified jail.
* specify the jail
* Specify the jail.
Here is an example of specifying the property and the jail:
@@ -659,7 +661,7 @@ jail, as both modes produce identical outputs:
"name": "response",
"namespace": "sysadm"
}
.. index:: df, iocage
.. _List Resource Usage:
@@ -667,9 +669,9 @@ jail, as both modes produce identical outputs:
List Resource Usage
===================
The "df" action lists resource usage for all jails. For each jail, the
response includes: CRT (compression ratio), RES (reserved space), QTA
(disk quota), USE (used space), AVA (available space), and TAG (jail
The "df" action lists resource usage for all jails. For each jail, the
response includes: CRT (compression ratio), RES (reserved space), QTA
(disk quota), USE (used space), AVA (available space), and TAG (jail
name).
**REST Request**
@@ -723,7 +725,7 @@ name).
"name": "response",
"namespace": "sysadm"
}
.. index:: startjail, iocage
.. _Start a Jail:
@@ -733,7 +735,7 @@ Start a Jail
The "startjail" action starts the specified jail.
.. note:: A jail can be started only once. If the jail is already
.. warning:: A jail can be started only once. If the jail is already
running, an error message will be generated.
**REST Request**
@@ -792,7 +794,7 @@ The "startjail" action starts the specified jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: stopjail, iocage
.. _Stop a Jail:
@@ -802,7 +804,7 @@ Stop a Jail
The "stopjail" action stops the specified jail.
.. note:: A jail can be only stopped once. If the jail has already
.. warning:: A jail can be only stopped once. If the jail has already
stopped, an error message will be generated.
**REST Request**
@@ -863,7 +865,7 @@ The "stopjail" action stops the specified jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: capjail, iocage
.. _Cap a Jail:
@@ -871,7 +873,7 @@ The "stopjail" action stops the specified jail.
Cap a Jail
===========
The "capjail" action re-applies resource limits to a running jail. Use
The "capjail" action re-applies resource limits to a running jail. Use
this action when you make a change to the specified jail's resources and
want to apply the changes without restarting the jail.
@@ -913,7 +915,7 @@ want to apply the changes without restarting the jail.
"name": "response",
"namespace": "sysadm"
}
.. index:: clonejail, iocage
.. _Clone a Jail:
@@ -921,13 +923,13 @@ want to apply the changes without restarting the jail.
Clone a Jail
============
The "clonejail" action clones the specified "jail". By default, the
clone will inherit that jail's properties. Use "props" to specify any
The "clonejail" action clones the specified "jail". By default, the
clone will inherit that jail's properties. Use "props" to specify any
properties that should differ. All available properties are described in
`iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
`iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
In this example, the "tag" property is specified so that the new jail
has a different name than the jail it was cloned from.
In this example, the "tag" property is specified so that the new jail
has a different name than the jail it was cloned from.
**REST Request**
@@ -973,7 +975,7 @@ has a different name than the jail it was cloned from.
"name": "response",
"namespace": "sysadm"
}
In this example, no properties are specified so iocage populates its own
values and the props returned in the response is empty:
@@ -1019,7 +1021,7 @@ values and the props returned in the response is empty:
"name": "response",
"namespace": "sysadm"
}
.. index:: createjail, iocage
.. _Create a Jail:
@@ -1027,11 +1029,13 @@ values and the props returned in the response is empty:
Create a Jail
=============
The "createjail" action creates a jail.
The "createjail" action creates a jail.
In this example, the "tag" property sets the name of the new jail and
In this example, the "tag" property sets the name of the new jail and
the "release" property specifies which template to use.
.. TODO CONTINUE EDITING BELOW------------------------------------------
**REST Request**
::