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

SysAdm PEP8 Conversion

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

31
api/classes/beadm.rst
View File

@@ -24,7 +24,8 @@ Every beadm class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listbes, beadm
@@ -33,8 +34,10 @@ The rest of this section provides examples of the available *actions* for each t
List Boot Environments
======================
The "listbes" action retrieves the list of boot environments. For each boot environment, the response includes its name, its flags (where "R" is active on reboot, "N" is active now and
"-" is inactive), the date it was created, its mount point, its nickname, and its size.
The "listbes" action retrieves the list of boot environments. For each
boot environment, the response includes its name, its flags (where "R"
is active on reboot, "N" is active now and "-" is inactive), the date it
was created, its mount point, its nickname, and its size.
**REST Request**
@@ -94,7 +97,9 @@ The "listbes" action retrieves the list of boot environments. For each boot envi
Rename a Boot Environment
=========================
The "renamebe" action renames the specified boot environment. When using this action, specify the new name as the "source" and the boot environment as the "target".
The "renamebe" action renames the specified boot environment. When using
this action, specify the new name as the "source" and the boot
environment as the "target".
**REST Request**
@@ -146,7 +151,8 @@ The "renamebe" action renames the specified boot environment. When using this ac
Activate Boot Environment
=========================
The "activatebe" action activates the specified boot environment (target) so that it will be the default at next boot.
The "activatebe" action activates the specified boot environment
(target) so that it will be the default at next boot.
**REST Request**
@@ -195,8 +201,10 @@ The "activatebe" action activates the specified boot environment (target) so tha
Create Boot Environment
=======================
The "create" action creates a new boot environment. Specify the name of the boot environment as the "newbe". By default, this action clones the active boot environment.
To specify another, inactive boot environment, also include "clonefrom" to specify which boot environment to clone from.
The "create" action creates a new boot environment. Specify the name of
the boot environment as the "newbe". By default, this action clones the
active boot environment. To specify another, inactive boot environment,
also include "clonefrom" to specify which boot environment to clone from.
**REST Request**
@@ -247,7 +255,8 @@ To specify another, inactive boot environment, also include "clonefrom" to speci
Destroy a Boot Environment
==========================
The "destroybe" action destroys the specified "target" boot environment and forcefully unmounts it.
The "destroybe" action destroys the specified "target" boot environment
and forcefully unmounts it.
**REST Request**
@@ -296,7 +305,8 @@ The "destroybe" action destroys the specified "target" boot environment and forc
Mount a Boot Environment
========================
The "mountbe" action mounts the specified boot environment. Use the optional "mountpoint" argument to specify the mount point.
The "mountbe" action mounts the specified boot environment. Use the
optional "mountpoint" argument to specify the mount point.
**REST Request**
@@ -347,7 +357,8 @@ The "mountbe" action mounts the specified boot environment. Use the optional "mo
Unmount a Boot Environment
==========================
The "umountbe" action forcibly unmounts the specified boot environment, even if it is in use.
The "umountbe" action forcibly unmounts the specified boot environment,
even if it is in use.
**REST Request**

15
api/classes/dispatcher.rst
View File

@@ -3,7 +3,8 @@
dispatcher
**********
The dispatcher class is used to spin up external processes on demand, such as a user running a custom system setup script.
The dispatcher class is used to spin up external processes on demand,
such as a user running a custom system setup script.
Every dispatcher class request contains the following parameters:
@@ -24,7 +25,8 @@ Every dispatcher class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list, dispatcher
@@ -33,7 +35,9 @@ The rest of this section provides examples of the available *actions* for each t
List Processes
==============
The "list" action lists all the currently running or pending processes within the dispatcher queues. Possible queues are "no_queue", "pkg_queue", and "iocage_queue".
The "list" action lists all the currently running or pending processes
within the dispatcher queues. Possible queues are "no_queue",
"pkg_queue", and "iocage_queue".
**REST Request**
@@ -67,7 +71,7 @@ The "list" action lists all the currently running or pending processes within th
"pkg_queue": {
"sysadm_pkg_install-{9c079421-ace9-4b6e-8870-d023b48f4c49}": {
"commands": [
"pkg install -y --repository \"pcbsd-major\" misc/pcbsd-meta-mate"
"pkg install -y --repository \"pcbsd-major\"misc/pcbsd-meta-mate"
],
"queue_position": "0",
"state": "running"
@@ -87,7 +91,8 @@ The "list" action lists all the currently running or pending processes within th
Kill Processes
==============
The "kill" action allows a user with full access to cancel pending or running jobs within the dispatcher system.
The "kill" action allows a user with full access to cancel pending or
running jobs within the dispatcher system.
**REST Request**

3
api/classes/fs.rst
View File

@@ -24,7 +24,8 @@ Every fs class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: dirlist, fs

91
api/classes/iocage.rst
View File

@@ -3,7 +3,9 @@
iocage
******
The iocage class is used to manage jails which provide a light-weight, operating system-level virtualization for running applications or services.
The iocage class is used to manage jails which provide a light-weight,
operating system-level virtualization for running applications or
services.
Every iocage class request contains the following parameters:
@@ -26,7 +28,8 @@ Every iocage class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: getdefaultsettings, iocage
@@ -35,7 +38,8 @@ The rest of this section provides examples of the available *actions* for each t
Default Settings
================
The "getdefaultsettings" action lists all of the global settings that apply to all jails.
The "getdefaultsettings" action lists all of the global settings that
apply to all jails.
**REST Request**
@@ -313,8 +317,12 @@ The "getdefaultsettings" action lists all of the global settings that apply to a
List Jails
==========
The "listjails" action lists information about currently installed jails. For each jail, the response includes the UUID of the jail, whether or not the jail has been configured to start at
system boot, the jail ID (only applies to running jails), whether or not the jail is running, a friendly name for the jail (tag), and the type of jail (basejail or thickjail).
The "listjails" action lists information about currently installed jails.
For each jail, the response includes the UUID of the jail, whether or
not the jail has been configured to start at system boot, the jail ID
(only applies to running jails), whether or not the jail is running, a
friendly name for the jail (tag), and the type of jail (basejail or
thickjail).
**REST Request**
@@ -386,7 +394,8 @@ system boot, the jail ID (only applies to running jails), whether or not the jai
Jail Settings
=============
The "getjailsettings" action lists settings that apply to the specified jail. This action supports 4 modes:
The "getjailsettings" action lists settings that apply to the specified
jail. This action supports 4 modes:
* specify a property and a jail
@@ -491,7 +500,8 @@ Here is an example of using *-r* and a specifed property:
"namespace": "sysadm"
}
An example of specifying either *all* and a jail, or just specifying the jail, as both modes produce identical outputs:
An example of specifying either *all* and a jail, or just specifying the
jail, as both modes produce identical outputs:
**REST Request**
@@ -657,8 +667,10 @@ An example of specifying either *all* and a jail, or just specifying the jail, a
List Resource Usage
===================
The "df" action lists resource usage for all jails. For each jail, the response includes: CRT (compression ratio), RES (reserved space), QTA (disk quota), USE (used space), AVA (available
space), and TAG (jail name).
The "df" action lists resource usage for all jails. For each jail, the
response includes: CRT (compression ratio), RES (reserved space), QTA
(disk quota), USE (used space), AVA (available space), and TAG (jail
name).
**REST Request**
@@ -721,7 +733,8 @@ Start a Jail
The "startjail" action starts the specified jail.
.. note:: since a jail can only be started once, you will receive an error if the jail is already running.
.. note:: since a jail can only be started once, you will receive an
error if the jail is already running.
**REST Request**
@@ -789,7 +802,8 @@ Stop a Jail
The "stopjail" action stops the specified jail.
.. note:: since a jail can only be stopped once, you will receive an error if the jail is not running.
.. note:: since a jail can only be stopped once, you will receive an
error if the jail is not running.
**REST Request**
@@ -857,8 +871,9 @@ The "stopjail" action stops the specified jail.
Cap a Jail
===========
The "capjail" action re-applies resource limits to a running jail. Use this action when you make a change to the specified jail's resources and want to apply the changes without restarting
the jail.
The "capjail" action re-applies resource limits to a running jail. Use
this action when you make a change to the specified jail's resources and
want to apply the changes without restarting the jail.
**REST Request**
@@ -906,10 +921,13 @@ the jail.
Clone a Jail
============
The "clonejail" action clones the specified "jail". By default, the clone will inherit that jail's properties. Use "props" to specify any properties that should differ. All available
properties are described in `iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
The "clonejail" action clones the specified "jail". By default, the
clone will inherit that jail's properties. Use "props" to specify any
properties that should differ. All available properties are described in
`iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_.
In this example, the "tag" property is specified so that the new jail has a different name than the jail it was cloned from.
In this example, the "tag" property is specified so that the new jail
has a different name than the jail it was cloned from.
**REST Request**
@@ -956,7 +974,8 @@ In this example, the "tag" property is specified so that the new jail has a diff
"namespace": "sysadm"
}
In this example, no properties are specified so iocage populates its own values and the props returned in the response is empty:
In this example, no properties are specified so iocage populates its own
values and the props returned in the response is empty:
**REST Request**
@@ -1010,7 +1029,8 @@ Create a Jail
The "createjail" action creates a jail.
In this example, the "tag" property sets the name of the new jail and the "release" property specifies which template to use.
In this example, the "tag" property sets the name of the new jail and
the "release" property specifies which template to use.
**REST Request**
@@ -1055,8 +1075,9 @@ In this example, the "tag" property sets the name of the new jail and the "relea
"namespace": "sysadm"
}
In this example, the **-e** switch, which creates an empty jail, is specified using "switches". Refer to `iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_ for the list
of available switches.
In this example, the **-e** switch, which creates an empty jail, is
specified using "switches". Refer to `iocage(8) <https://github.com/iocage/iocage/blob/master/iocage.8.txt>`_
for the list of available switches.
**REST Request**
@@ -1110,7 +1131,9 @@ of available switches.
Destroy a Jail
==============
The "destroyjail" action destroys the specified jail. This action is irreversible and does not prompt for confirmation, but will fail if the jail is running.
The "destroyjail" action destroys the specified jail. This action is
irreversible and does not prompt for confirmation, but will fail if the
jail is running.
**REST Request**
@@ -1160,8 +1183,10 @@ The "destroyjail" action destroys the specified jail. This action is irreversibl
Run Command
===========
The "execjail" action executes the specified "command" under the privileges of the specified "user" in the specified "jail". The response will indicate whether or not command execution
succeeded as well as any output from the command.
The "execjail" action executes the specified "command" under the
privileges of the specified "user" in the specified "jail". The response
will indicate whether or not command execution succeeded as well as any
output from the command.
**REST Request**
@@ -1215,7 +1240,8 @@ succeeded as well as any output from the command.
Clean Jails
===========
The "cleanjails" action destroys all existing jail datasets, including all data stored in the jails.
The "cleanjails" action destroys all existing jail datasets, including
all data stored in the jails.
**REST Request**
@@ -1261,7 +1287,9 @@ The "cleanjails" action destroys all existing jail datasets, including all data
Clean Releases
==============
The "cleanreleases" action deletes all releases that have been fetched. Since basejails rely on releases, do not run this action if any basejails still exist.
The "cleanreleases" action deletes all releases that have been fetched.
Since basejails rely on releases, do not run this action if any
basejails still exist.
**REST Request**
@@ -1403,7 +1431,9 @@ The "cleanall" action destroys everything associated with iocage.
Activate a Pool
===============
The "activatepool" action can be used to specify which ZFS pool is used to store jails. If you do not specify the pool, the response will indicate the current setting.
The "activatepool" action can be used to specify which ZFS pool is used
to store jails. If you do not specify the pool, the response will
indicate the current setting.
These examples specify the pool to use:
@@ -1520,9 +1550,12 @@ These examples show responses when the pool is not specified:
Deactivate a Pool
=================
Since only one pool can be active, the "deactivatepool" action can be used to deactivate a currently active pool. This should be done before using the
"activatepool" action to activate a different pool. When a pool is deactivated, no data is removed. However, you won't have access to its jails unless you move those datasets to the newly
activated pool or activate the old pool again.
Since only one pool can be active, the "deactivatepool" action can be
used to deactivate a currently active pool. This should be done before
using the "activatepool" action to activate a different pool. When a
pool is deactivated, no data is removed. However, you won't have access
to its jails unless you move those datasets to the newly activated pool
or activate the old pool again.
**REST Request**

50
api/classes/iohyve.rst
View File

@@ -3,7 +3,8 @@
iohyve
******
The iohyve class is used to manage virtual machines (VMs) running in the bhyve type 2 hypervisor.
The iohyve class is used to manage virtual machines (VMs) running in the
bhyve type 2 hypervisor.
Every iohyve class request contains the following parameters:
@@ -26,7 +27,8 @@ Every iohyve class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listvms, iohyve
@@ -35,8 +37,11 @@ The rest of this section provides examples of the available *actions* for each t
List VMs
========
The "listvms" action lists information about currently installed VMs. For each VM, the response includes the VM's name, description, whether or not it is scheduled to start when the host
system boots, whether or not it is currently running, and whether or not the VM is currently loaded into memory.
The "listvms" action lists information about currently installed VMs.
For each VM, the response includes the VM's name, description, whether
or not it is scheduled to start when the host system boots, whether or
not it is currently running, and whether or not the VM is currently
loaded into memory.
**REST Request**
@@ -104,9 +109,9 @@ system boots, whether or not it is currently running, and whether or not the VM
Fetch ISO
=========
The "fetchiso" action is used to retrieve the installation ISO. It is used with the "url" argument which contains the ISO address beginning with *http://*,
*ftp://*, or
*file://*.
The "fetchiso" action is used to retrieve the installation ISO. It is
used with the "url" argument which contains the ISO address beginning
with *http://*, *ftp://*, or *file://*.
**REST Request**
@@ -227,7 +232,8 @@ The "listisos" action lists all the known ISO files which iohyve can use.
Rename ISO
==========
The "renameiso" action is used to to rename an existing ISO file on disk. Specify the existing name with "source" and the new name with "target".
The "renameiso" action is used to to rename an existing ISO file on disk.
Specify the existing name with "source" and the new name with "target".
**REST Request**
@@ -278,7 +284,8 @@ The "renameiso" action is used to to rename an existing ISO file on disk. Specif
Remove ISO
==========
The "rmiso" action is used to to remove an existing ISO file from disk. Specify the ISO's name as the "target".
The "rmiso" action is used to to remove an existing ISO file from disk.
Specify the ISO's name as the "target".
**REST Request**
@@ -326,7 +333,9 @@ The "rmiso" action is used to to remove an existing ISO file from disk. Specify
Setup iohyve
============
The "setup" action performs the initial setup of iohyve. It is mandatory to specify the FreeBSD device name of the "nic" and the ZFS "pool" to use.
The "setup" action performs the initial setup of iohyve. It is mandatory
to specify the FreeBSD device name of the "nic" and the ZFS "pool" to
use.
**REST Request**
@@ -377,7 +386,8 @@ The "setup" action performs the initial setup of iohyve. It is mandatory to spec
Determine iohyve Setup
======================
The "issetup" action queries if iohyve has been setup and returns either "true" or "false".
The "issetup" action queries if iohyve has been setup and returns either
"true" or "false".
**REST Request**
@@ -423,7 +433,8 @@ The "issetup" action queries if iohyve has been setup and returns either "true"
Create Guest
============
The "create" action creates a new iohyve guest of the specified "name" and "size".
The "create" action creates a new iohyve guest of the specified "name"
and "size".
**REST Request**
@@ -474,8 +485,10 @@ The "create" action creates a new iohyve guest of the specified "name" and "size
Install Guest
=============
The "install" action starts the iohyve installation of the specified guest from the specified ISO. This action only boots the VM with the ISO; to do the actual installation,
run :command:`iohyve console <name>` from the system.
The "install" action starts the iohyve installation of the specified
guest from the specified ISO. This action only boots the VM with the ISO;
to do the actual installation, run :command:`iohyve console <name>` from
the system.
**REST Request**
@@ -770,7 +783,9 @@ The "listdisks" action lists the disks connected to the specified VM.
Resize a Disk
=============
The "resizedisk" action **increases** the specified disk in the specified VM. The new specified size must be larger than the current size.
The "resizedisk" action **increases** the specified disk in the
specified VM. The new specified size must be larger than the current
size.
**REST Request**
@@ -984,8 +999,9 @@ The "getprops" action lists the properties for the specified guest.
Set Guest Properties
=====================
The "setprop" action can be used to modify the properties for the specified guest. For each property, specify its name and desired value. Use "getprops" to see the current properties
and values for the guest.
The "setprop" action can be used to modify the properties for the
specified guest. For each property, specify its name and desired value.
Use "getprops" to see the current properties and values for the guest.
**REST Request**

78
api/classes/lifepreserver.rst
View File

@@ -3,7 +3,8 @@
lifepreserver
*************
The lifepreserver class is used to manage and retrieve information about scheduled snapshots and replication.
The lifepreserver class is used to manage and retrieve information about
scheduled snapshots and replication.
Every lifepreserver class request contains the following parameters:
@@ -26,7 +27,8 @@ Every lifepreserver class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: listcron, Life Preserver
@@ -35,8 +37,11 @@ The rest of this section provides examples of the available *actions* for each t
List Schedules
==============
The "listcron" action retrieves the information for each Life Preserver scheduled task. If snapshots have been configured for a ZFS pool, it lists the number of snapshots to keep and
the time that snapshots are taken. If scrubs have been configured on that ZFS pool, it also lists the time that ZFS scrubs occur.
The "listcron" action retrieves the information for each Life Preserver
scheduled task. If snapshots have been configured for a ZFS pool, it
lists the number of snapshots to keep and the time that snapshots are
taken. If scrubs have been configured on that ZFS pool, it also lists
the time that ZFS scrubs occur.
**REST Request**
@@ -103,7 +108,8 @@ the time that snapshots are taken. If scrubs have been configured on that ZFS po
Create a Snapshot Schedule
==========================
The "cronsnap" action is used to create snapshot schedules for Life Preserver. This action supports the following parameters:
The "cronsnap" action is used to create snapshot schedules for Life
Preserver. This action supports the following parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
@@ -187,7 +193,8 @@ The "cronsnap" action is used to create snapshot schedules for Life Preserver. T
Create a Scrub Schedule
==========================
The "cronscrub" action is used to schedule a ZFS scrub. This action supports the following parameters:
The "cronscrub" action is used to schedule a ZFS scrub. This action
supports the following parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
@@ -264,7 +271,8 @@ The "cronscrub" action is used to schedule a ZFS scrub. This action supports the
Create a Snapshot
=================
The "createsnap" action creates a one-time snapshot of the specified dataset.
The "createsnap" action creates a one-time snapshot of the specified
dataset.
**REST Request**
@@ -400,10 +408,14 @@ The "listsnap" action retrieves the list of saved snapshots.
Revert a Snapshot
=================
The "revertsnap" action is used to rollback the contents of the specified dataset to the point in time that the specified snapshot was taken.
The "revertsnap" action is used to rollback the contents of the
specified dataset to the point in time that the specified snapshot was
taken.
.. warning:: performing this operation will revert the contents of the dataset back in time, meaning that all changes to the dataset's files that occurred since the snapshot was taken will
be lost.
.. warning:: performing this operation will revert the contents of the
dataset back in time, meaning that all changes to the
dataset's files that occurred since the snapshot was taken
will be lost.
**REST Request**
@@ -467,7 +479,8 @@ The "revertsnap" action is used to rollback the contents of the specified datase
Remove a Snapshot
=================
The "removesnap" action is used to remove a ZFS snapshot from the specified dataset or pool.
The "removesnap" action is used to remove a ZFS snapshot from the
specified dataset or pool.
**REST Request**
@@ -531,7 +544,8 @@ The "removesnap" action is used to remove a ZFS snapshot from the specified data
Add Replication
===============
The "addreplication" action is used to create a replication task in Life Preserver. This action supports the following parameters:
The "addreplication" action is used to create a replication task in Life
Preserver. This action supports the following parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |
@@ -641,8 +655,9 @@ The "addreplication" action is used to create a replication task in Life Preserv
Remove Replication
==================
The "removereplication" action is used to delete an existing replication task. Note that this action only deletes the task--it does not remove any already replicated data from the
remote system.
The "removereplication" action is used to delete an existing replication
task. Note that this action only deletes the task--it does not remove
any already replicated data from the remote system.
This action supports the following parameters:
@@ -719,9 +734,14 @@ This action supports the following parameters:
List Replications
=================
The "listreplication" action is used to retrieve the settings of configured replication tasks. For each task, the response includes the name of the local ZFS pool or dataset to replicate,
the IP address and listening port number of the remote system to replicate to, when the replication occurs (see the "frequency" description in :ref:`Add Replication`), the name of the
dataset on the remote system to store the replicated data ("rdset"), and the name of the replication user account.
The "listreplication" action is used to retrieve the settings of
configured replication tasks. For each task, the response includes the
name of the local ZFS pool or dataset to replicate, the IP address and
listening port number of the remote system to replicate to, when the
replication occurs (see the "frequency" description in
:ref:`Add Replication`), the name of the dataset on the remote system to
store the replicated data ("rdset"), and the name of the replication
user account.
**REST Request**
@@ -793,7 +813,8 @@ dataset on the remote system to store the replicated data ("rdset"), and the nam
Start Replication
=================
The "runreplication" action can be used to manually replicate the specified dataset to the specified remote server.
The "runreplication" action can be used to manually replicate the
specified dataset to the specified remote server.
**REST Request**
@@ -857,8 +878,10 @@ The "runreplication" action can be used to manually replicate the specified data
Initialize Replication
======================
The "initreplication" action can be used to clear the replication data on the remote server. This is useful if a replication becomes stuck. After running this action, issue a
"runreplication" action to start a new replication.
The "initreplication" action can be used to clear the replication data
on the remote server. This is useful if a replication becomes stuck.
After running this action, issue a "runreplication" action to start a
new replication.
The "initreplication" action supports the following parameters:
@@ -935,10 +958,15 @@ The "initreplication" action supports the following parameters:
View Settings
=============
The "settings" action returns the system-wide settings of the Life Preserver utility. The returned settings include the disk percentage used at which Life Preserver will issue a warning, the
level at which an email will be sent, the email address to send notifications to, and whether or not snapshots are taken recursively (include all child datasets).
The "settings" action returns the system-wide settings of the Life
Preserver utility. The returned settings include the disk percentage
used at which Life Preserver will issue a warning, the level at which an
email will be sent, the email address to send notifications to, and
whether or not snapshots are taken recursively (include all child
datasets).
Run :command:`lpreserver help set` for more information about each available setting.
Run :command:`lpreserver help set` for more information about each
available setting.
**REST Request**
@@ -1002,7 +1030,9 @@ Run :command:`lpreserver help set` for more information about each available set
Save Settings
=============
The "savesettings" action can be used to modify the system-wide settings of the Life Preserver utility. This action supports the following parameters:
The "savesettings" action can be used to modify the system-wide settings
of the Life Preserver utility. This action supports the following
parameters:
+---------------------------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Description** |

31
api/classes/logs.rst
View File

@@ -3,7 +3,8 @@
logs
****
The logs class is used to interact with the log files created by the SysAdm server.
The logs class is used to interact with the log files created by the
SysAdm server.
Every logs class request contains the following parameters:
@@ -24,7 +25,8 @@ Every logs class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: read_logs, logs
@@ -33,20 +35,29 @@ The rest of this section provides examples of the available *actions* for each t
Read Logs
=========
The "read_logs" action can be used to display log entries. It supports the following optional arguments:
The "read_logs" action can be used to display log entries. It supports
the following optional arguments:
* **logs:** used to specify an array or string of log type(s). Valid types are "hostinfo", "dispatcher", "events-dispatcher","events-lifepreserver", and "events-state".
* **logs:** used to specify an array or string of log type(s). Valid
types are "hostinfo", "dispatcher", "events-dispatcher",
"events-lifepreserver", and "events-state".
* **time_format:** used to specify the format for "start_time" and "end_time". Valid Formats are "time_t_seconds", "epoch_mseconds, "relative_[day/month/second]", or a
`QDateTime String code <http://doc.qt.io/qt-5/qdatetime.html#fromString>`_.
* **time_format:** used to specify the format for "start_time" and
"end_time". Valid Formats are "time_t_seconds", "epoch_mseconds,
"relative_[day/month/second]", or a `QDateTime String code <http://doc.qt.io/qt-5/qdatetime.html#fromString>`_.
* **start_time:** displays log entries that occurred after the time specified using a valid "time_format".
* **start_time:** displays log entries that occurred after the time
specified using a valid "time_format".
* **end_time:** displays log entries that occurred before the time specified using a valid "time_format".
* **end_time:** displays log entries that occurred before the time
specified using a valid "time_format".
If the "time_format" is not specified, or if the "start_time" or "end_time" are not defined, the end time will be the current date and time and the start time will be 12 hours previous.
If the "time_format" is not specified, or if the "start_time" or
"end_time" are not defined, the end time will be the current date and
time and the start time will be 12 hours previous.
If the "logs" argument is missing or empty, then all logs matching the search parameters will be returned.
If the "logs" argument is missing or empty, then all logs matching the
search parameters will be returned.
For example, this input returns all log entries within the last hour:

14
api/classes/network.rst
View File

@@ -3,7 +3,8 @@
network
*******
The network class is used to manage and retrieve information from Ethernet and wireless network devices.
The network class is used to manage and retrieve information from
Ethernet and wireless network devices.
Every network class request contains the following parameters:
@@ -24,7 +25,8 @@ Every network class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list-devices, network
@@ -33,8 +35,12 @@ The rest of this section provides examples of the available *actions* for each t
List Devices
============
The "list-devices" action lists information about currently recognized network devices. For each network device, the response includes the device's MAC address, description, IPv4 address,
IPv6 address, whether or not the device is active, whether or not the device is configured using DHCP, whether or not the device is wireless, its subnet mask, and its current status.
The "list-devices" action lists information about currently recognized
network devices. For each network device, the response includes the
device's MAC address, description, IPv4 address, IPv6 address, whether
or not the device is active, whether or not the device is configured
using DHCP, whether or not the device is wireless, its subnet mask, and
its current status.
**REST Request**

105
api/classes/pkg.rst
View File

@@ -25,7 +25,8 @@ Every pkg class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: pkg_info, pkg
@@ -34,15 +35,20 @@ The rest of this section provides examples of the available *actions* for each t
Package Information
===================
The "pkg_info" action reads the pkg database directly and returns any relevant information. The following arguments are optional:
The "pkg_info" action reads the pkg database directly and returns any
relevant information. The following arguments are optional:
* **"repo"**: unless specified, defaults to the local package repository.
* **"pkg_origins"**: unless specified, information for all installed packages will be listed.
* **"pkg_origins"**: unless specified, information for all installed
packages will be listed.
* **"category"**: limits the results to packages within the specified category.
* **"category"**: limits the results to packages within the specified
category.
* **"result"**: must be set to "full" to retrieve all of the information with multiple possible values, such as "dependencies", "options", and "licences".
* **"result"**: must be set to "full" to retrieve all of the information
with multiple possible values, such as "dependencies", "options", and
"licences".
**REST Request**
@@ -231,11 +237,14 @@ The "pkg_info" action reads the pkg database directly and returns any relevant i
Search Packages
===============
The "pkg_search" action searches the package database for pkgs which match the given "search_term" (required). These parameters are optional:
The "pkg_search" action searches the package database for pkgs which
match the given "search_term" (required). These parameters are optional:
* **"repo"**: may be used to specifiy searching the specified repository. If not specified, the local package database is searched.
* **"repo"**: may be used to specifiy searching the specified repository.
If not specified, the local package database is searched.
* **"category"**: may be used to restrict searches to the specified package category.
* **"category"**: may be used to restrict searches to the specified
package category.
**REST Request**
@@ -412,7 +421,9 @@ The "pkg_search" action searches the package database for pkgs which match the g
List Categories
===============
The "list_categories" action lists all the known, non-empty categories within the specified repository or, if no repository is specified, the local repository.
The "list_categories" action lists all the known, non-empty categories
within the specified repository or, if no repository is specified, the
local repository.
**REST Request**
@@ -511,8 +522,10 @@ The "list_categories" action lists all the known, non-empty categories within th
List Repositories
=================
The "list_repositories" action scan the package repository configuration files and returns the names of the available repositories. All of the repositories returned by this
action are valid as the optional "repo" argument for the other pkg API actions.
The "list_repositories" action scan the package repository configuration
files and returns the names of the available repositories. All of the
repositories returned by this action are valid as the optional "repo"
argument for the other pkg API actions.
**REST Request**
@@ -559,10 +572,16 @@ action are valid as the optional "repo" argument for the other pkg API actions.
Audit Packages
==============
The "pkg_audit" action performs an audit of all installed packages and reports any packages with known vulnerabilities as well as other packages which are impacted by those vulnerabilities.
The "pkg_audit" action performs an audit of all installed packages and
reports any packages with known vulnerabilities as well as other
packages which are impacted by those vulnerabilities.
.. note:: the vulnerability information will be returned as a dispatcher event as this action just queues up the results of the :command:`pkg` operation. This is due to a limitation of
:command:`pkg`, as it only supports one process call at a time. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
.. note:: the vulnerability information will be returned as a dispatcher
event as this action just queues up the results of the :command:`pkg`
operation. This is due to a limitation of :command:`pkg`, as it only
supports one process call at a time. Refer to the
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to
and query dispatcher events.
**REST Request**
@@ -634,8 +653,10 @@ The "pkg_audit" action performs an audit of all installed packages and reports a
Upgrade Packages
================
The "pkg_upgrade" action upgrades all currently installed packages. The messages from the upgrade will be returned as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for
instructions on how to subscribe to and query dispatcher events.
The "pkg_upgrade" action upgrades all currently installed packages. The
messages from the upgrade will be returned as a dispatcher event. Refer
to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe
to and query dispatcher events.
**REST Request**
@@ -707,8 +728,10 @@ instructions on how to subscribe to and query dispatcher events.
Check Packages
==============
The "pkg_check_upgrade" action checks to see if there are any package updates available and returns that information as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for
instructions on how to subscribe to and query dispatcher events.
The "pkg_check_upgrade" action checks to see if there are any package
updates available and returns that information as a dispatcher event.
Refer to the :ref:`Dispatcher Subsystem` for instructions on how to
subscribe to and query dispatcher events.
**REST Request**
@@ -781,10 +804,14 @@ instructions on how to subscribe to and query dispatcher events.
Update Package Database
=======================
The "pkg_update" action instructs :command:`pkg` to update its databases. This action is typically not required. It returns any information as a dispatcher event. Refer to the
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
The "pkg_update" action instructs :command:`pkg` to update its databases.
This action is typically not required. It returns any information as a
dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for
instructions on how to subscribe to and query dispatcher events.
If you include "force" = "true", it forces :command:`pkg` to completely resync all of its databases with all known repositories which may take some time.
If you include "force" = "true", it forces :command:`pkg` to completely
resync all of its databases with all known repositories which may take
some time.
**REST Request**
@@ -858,12 +885,17 @@ If you include "force" = "true", it forces :command:`pkg` to completely resync a
Lock/Unlock Packages
====================
The "pkg_lock" action locks the specified "pkg_origins" so that it will be skipped during a package upgrade and remain at its current version. When using "pkg_origins", specify either a
single package origin string or an array of package origins.
The "pkg_lock" action locks the specified "pkg_origins" so that it will
be skipped during a package upgrade and remain at its current version.
When using "pkg_origins", specify either a single package origin string
or an array of package origins.
The "pkg_unlock" action unlocks the previously locked "pkg_origins" so that it is no longer skipped during a package upgrade.
The "pkg_unlock" action unlocks the previously locked "pkg_origins" so
that it is no longer skipped during a package upgrade.
Both actions return any information as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
Both actions return any information as a dispatcher event. Refer to the
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and
query dispatcher events.
**REST Request**
@@ -1006,9 +1038,13 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di
Install Packages
================
The "pkg_install" action installs the specified "pkg_origins" on the system. When using "pkg_origins", specify either a single package origin string or an array of package origins.
Unless the "repo" is specified, :command:`pkg` will automatically determine the repository. The install messages will be returned as a dispatcher event. Refer to the
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
The "pkg_install" action installs the specified "pkg_origins" on the
system. When using "pkg_origins", specify either a single package origin
string or an array of package origins. Unless the "repo" is specified,
:command:`pkg` will automatically determine the repository. The install
messages will be returned as a dispatcher event. Refer to the
:ref:`Dispatcher Subsystem` for instructions on how to subscribe to and
query dispatcher events.
**REST Request**
@@ -1084,12 +1120,17 @@ Unless the "repo" is specified, :command:`pkg` will automatically determine the
Uninstall Packages
==================
The "pkg_remove" action uninstalls the specified "pkg_origins" from the system. When using "pkg_origins", specify either a single package origin string or an array of package origins.
The "pkg_remove" action uninstalls the specified "pkg_origins" from the
system. When using "pkg_origins", specify either a single package origin
string or an array of package origins.
The optional "recursive" argument can be set to "true" or "false". The default is "true", which means that other packages which depend on this package will also be removed so that there are
no broken dependencies.
The optional "recursive" argument can be set to "true" or "false". The
default is "true", which means that other packages which depend on this
package will also be removed so that there are no broken dependencies.
The uninstall messages will be returned as a dispatcher event. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
The uninstall messages will be returned as a dispatcher event. Refer to
the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to
and query dispatcher events.
**REST Request**

45
api/classes/systemmanager.rst
View File

@@ -3,7 +3,8 @@
systemmanager
*************
The systemmanager class is used to retrieve information about the system. Every systemmanager class request contains the following parameters:
The systemmanager class is used to retrieve information about the system.
Every systemmanager class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
@@ -23,7 +24,8 @@ The systemmanager class is used to retrieve information about the system. Every
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: memorystats, systemmanager
@@ -32,7 +34,8 @@ The rest of this section provides examples of the available *actions* for each t
Memory Statistics
=================
The "memorystats" action returns memory statistics, including the amount of active, cached, free, inactive, and total physical (wired) memory.
The "memorystats" action returns memory statistics, including the amount
of active, cached, free, inactive, and total physical (wired) memory.
**REST Request**
@@ -244,8 +247,10 @@ The "cputemps" action returns the temperature of each CPU.
Process Information
===================
The "procinfo" action lists information about each running process. Since a system will have many running processes, the responses in this section only show one process as an example
of the type of information listed by this action.
The "procinfo" action lists information about each running process.
Since a system will have many running processes, the responses in this
section only show one process as an example of the type of information
listed by this action.
**REST Request**
@@ -326,7 +331,9 @@ of the type of information listed by this action.
Kill a Process
==============
The "killproc" action can be used to send the specified signal to the specified Process ID (PID). The following signals are supported: INT, QUIT, ABRT, KILL, ALRM, or TERM.
The "killproc" action can be used to send the specified signal to the
specified Process ID (PID). The following signals are supported: INT,
QUIT, ABRT, KILL, ALRM, or TERM.
**REST Request**
@@ -392,8 +399,10 @@ The "killproc" action can be used to send the specified signal to the specified
Battery Information
===================
The "batteryinfo" action will indicate whether or not a battery exists. If it does, it will also report its current charge percentage level (1-99). its
status (offline, charging, on backup, or unknown), and estimated time left (in seconds).
The "batteryinfo" action will indicate whether or not a battery exists.
If it does, it will also report its current charge percentage level
(1-99). its status (offline, charging, on backup, or unknown), and
estimated time left (in seconds).
**REST Request**
@@ -451,8 +460,10 @@ status (offline, charging, on backup, or unknown), and estimated time left (in s
List External Mounts
====================
The "externalmounts" action returns a list of mounted external devices. Supported device types are UNKNOWN, USB, HDRIVE (external hard drive), DVD, and SDCARD.
For each mounted device, the response will include the device name, filesystem, mount path, and device type.
The "externalmounts" action returns a list of mounted external devices.
Supported device types are UNKNOWN, USB, HDRIVE (external hard drive),
DVD, and SDCARD. For each mounted device, the response will include the
device name, filesystem, mount path, and device type.
**REST Request**
@@ -518,8 +529,10 @@ For each mounted device, the response will include the device name, filesystem,
System Information
==================
The "systemmanager" action lists system information, including the architecture, number of CPUs, type of CPU, hostname, kernel name and version, system version and patch level, total amount
of RAM, and the system's uptime.
The "systemmanager" action lists system information, including the
architecture, number of CPUs, type of CPU, hostname, kernel name and
version, system version and patch level, total amount of RAM, and the
system's uptime.
**REST Request**
@@ -593,7 +606,9 @@ of RAM, and the system's uptime.
List Sysctls
============
The "sysctllist" action lists returns the list of all setable sysctl values. Since there are many, the example responses in this section have been truncated to just show a few.
The "sysctllist" action lists returns the list of all setable sysctl
values. Since there are many, the example responses in this section have
been truncated to just show a few.
**REST Request**
@@ -667,7 +682,9 @@ The "sysctllist" action lists returns the list of all setable sysctl values. Sin
Set a Sysctl
============
The "setsysctl" action sets the specified setable sysctl to the specified value. The response indicates that the old value was changed to the new value.
The "setsysctl" action sets the specified setable sysctl to the
specified value. The response indicates that the old value was changed
to the new value.
**REST Request**

32
api/classes/updates.rst
View File

@@ -3,7 +3,8 @@
update
******
The update class is used to check for and manage system and software updates.
The update class is used to check for and manage system and software
updates.
Every update class request contains the following parameters:
@@ -24,7 +25,8 @@ Every update class request contains the following parameters:
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: checkupdates, update
@@ -33,8 +35,11 @@ The rest of this section provides examples of the available *actions* for each t
Check for Updates
=================
The "checkupdates" action queries the update server to see if any updates are available. If an update is available, the response will indicate if it is a system security update, an
upgrade to a newer version of the operating system, a system patch, or an update to installed software packages.
The "checkupdates" action queries the update server to see if any
updates are available. If an update is available, the response will
indicate if it is a system security update, an upgrade to a newer
version of the operating system, a system patch, or an update to
installed software packages.
**REST Request**
@@ -92,7 +97,9 @@ upgrade to a newer version of the operating system, a system patch, or an update
List Branches
=============
The "listbranches" action retrieves the list of available branches (operating system versions). The currently installed version will be listed as "active".
The "listbranches" action retrieves the list of available branches
(operating system versions). The currently installed version will be
listed as "active".
**REST Request**
@@ -152,17 +159,24 @@ The "listbranches" action retrieves the list of available branches (operating sy
Start Updates
=============
The "startupdate" action starts the specified update. You must specify a "target" to indicate the type of update to perform. The available targets are:
The "startupdate" action starts the specified update. You must specify a
"target" to indicate the type of update to perform. The available
targets are:
* **chbranch:** will update to the specified "branch" (operating system version). You can determine which branches are available by using the "listbranches" action.
* **chbranch:** will update to the specified "branch" (operating system
version). You can determine which branches are available by using the
"listbranches" action.
* **pkgupdate:** only update installed software.
* **fbsdupdate:** only apply FreeBSD system updates.
* **fbsdupdatepkgs:** update installed software and apply FreeBSD system updates.
* **fbsdupdatepkgs:** update installed software and apply FreeBSD system
updates.
* **standalone:** only apply the update specified as a "tag". Use the "checkupdates" action to determine the name (tag) of the update to specify.
* **standalone:** only apply the update specified as a "tag". Use the
"checkupdates" action to determine the name (tag) of the update to
specify.
**REST Request**

46
api/classes/zfs.rst
View File

@@ -7,24 +7,25 @@ The zfs class is used to manage and retrieve information about ZFS pools.
Every zfs class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | zfs | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "list_pools", "datasets" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+---------------------------------+---------------+------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+==============================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| name | zfs | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| action | | supported actions include "list_pools", "datasets" |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
The rest of this section provides examples of the available *actions* for each type of request, along with their responses.
The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.
.. index:: list_pools, zfs
@@ -33,9 +34,14 @@ The rest of this section provides examples of the available *actions* for each t
List Pools
==========
The "list_pools" action lists pool information. For each ZFS pool, the response includes the pool name, the amount of space that has been physically allocated, whether or not an alternate
root has been defined, capacity (percent used), the deduplication ratio, amount of uninitialized space (expandsz, which usually applies to LUNs), percentage of fragmentation, amount of free
space, pool health, and total size. This action is the equivalent of running :command:`zpool list` from the command line.
The "list_pools" action lists pool information. For each ZFS pool, the
response includes the pool name, the amount of space that has been
physically allocated, whether or not an alternate root has been defined,
capacity (percent used), the deduplication ratio, amount of
uninitialized space (expandsz, which usually applies to LUNs),
percentage of fragmentation, amount of free space, pool health, and
total size. This action is the equivalent of running
:command:`zpool list` from the command line.
**REST Request**