Merge branch 'master' of github.com:trueos/sysadm

This commit is contained in:
Ken Moore
2016-08-16 11:46:50 -04:00
4 changed files with 676 additions and 47 deletions

View File

@@ -5,7 +5,7 @@ beadm
The beadm class is used to manage boot environments.
Every beadm class request contains the following parameters:
Every beadm class request contains several parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |

View File

@@ -8,26 +8,78 @@ updates.
Every update class request contains the following parameters:
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+======================================================================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| name | update | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| namespace | sysadm | |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
| action | | supported actions include "checkupdates", "listbranches", "startupdate" |
| | | |
+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
+----------------+------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+================+============+=======================================+
| id | | any unique value for the request; |
| | | examples include a hash, checksum, or |
| | | uuid |
+----------------+------------+---------------------------------------+
| name | update | |
| | | |
+----------------+------------+---------------------------------------+
| namespace | sysadm | |
| | | |
+----------------+------------+---------------------------------------+
| action | | supported 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.
.. index:: changesettings, update
.. _Change Settings:
Change Settings
===============
Use :command:`changesettings` to change the various updatemanager
settings (maxbe, package_set, package_url, auto_update).
**REST Request**
::
PUT /sysadm/update
{
"action" : "changesettings",
"maxbe" : "6"
}
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"name" : "update",
"namespace" : "sysadm",
"args" : {
"maxbe" : "6",
"action" : "changesettings"
}
}
**Response**
.. code-block:: json
{
"args": {
"changesettings": {
"result": "success"
}
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: checkupdates, update
.. _Check for Updates:
@@ -56,6 +108,7 @@ installed software packages.
{
"args": {
"last_check" : "<ISO date/time stamp>",
"checkupdates": {
"status": "noupdates"
}
@@ -69,18 +122,20 @@ installed software packages.
{
"name" : "update",
"args" : {
"action" : "checkupdates"
"action" : "checkupdates",
"force":"[true/false]"
},
"namespace" : "sysadm",
"id" : "fooid"
}
**WebSocket Response**
**Response**
.. code-block:: json
{
"args": {
"last_check" : "<ISO date/time stamp>",
"checkupdates": {
"status": "noupdates"
}
@@ -151,7 +206,54 @@ listed as "active".
"name": "response",
"namespace": "sysadm"
}
.. index:: listsettings, update
.. _List Settings:
List Settings
=============
:command:`listsettings` shows all of the current settings.
**REST Request**
::
PUT /sysadm/update
{
"action" : "listsettings"
}
**WebSocket Request**
.. code-block:: json
{
"args" : {
"action" : "listsettings"
},
"id" : "fooid",
"namespace" : "sysadm",
"name" : "update"
}
**Response**
.. code-block:: json
{
"args": {
"listsettings": {
"maxbe": " 5",
"package_set": " EDGE"
}
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: startupdate, update
.. _Start Updates:
@@ -169,11 +271,6 @@ targets are:
* **pkgupdate:** only update installed software.
* **fbsdupdate:** only 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.
@@ -254,4 +351,39 @@ targets are:
"state" : "finished"
}
}
}
}
.. index:: stopupdate, update
.. _Stop Updates:
Stop Updates
============
This will look for any currently-running pc-updatemanager processes
and kill/stop them as needed.
**Websocket Request**
.. code-block:: json
{
"id":"dummy",
"namespace":"sysadm",
"name":"update",
"args": {
"action":"stopupdate"
}
}
**Websocket Response**
.. code-block:: json
{
"args":{
"stopupdate": {
"result": "success"
}
}
}

499
api/classes/users.rst Normal file
View File

@@ -0,0 +1,499 @@
.. _users:
users
*****
The users class is used to manage users and groups on the system.
Every user request will have several parameters:
+----------------+------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+================+============+=======================================+
| id | | any unique value for the request; |
| | | examples include a hash, checksum, |
| | | or uuid |
+----------------+------------+---------------------------------------+
| name | users | |
| | | |
+----------------+------------+---------------------------------------+
| namespace | sysadm | |
| | | |
+----------------+------------+---------------------------------------+
| action | | "groupadd", "groupdelete", |
| | | "groupshow", "personacrypt_listdevs", |
| | | "useradd", "userdelete", "usermod", |
| | | "usershow" |
+----------------+------------+---------------------------------------+
.. index:: groupadd, users
.. _groupadd:
Group Add
=========
:command:`groupadd` will create a new group on the system. The "name"
field is required, the "gid" and "users" fields are optional.
**REST Request**
::
PUT /sysadm/users
{
"action" : "groupadd",
"name" : "testgroup"
}
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"namespace" : "sysadm",
"args" : {
"action" : "groupadd",
"name" : "testgroup"
},
"name" : "users"
}
**Response**
.. code-block:: json
{
"args": {
"result": "success"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: groupdelete, users
.. _groupdelete:
Group Delete
============
:command:`groupdelete` deletes the designated group.
**REST Request**
::
PUT /sysadm/users
{
"action" : "groupdelete",
"name" : "groupToDelete"
}
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"namespace" : "sysadm",
"args" : {
"action" : "groupdelete",
"name" : "<groupToDelete>"
},
"name" : "users"
}
**Response**
.. code-block:: json
{
"args": {
"result": "success"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: groupshow, users
.. _groupshow:
Group Show
==========
The action :command:`groupshow` lists all the known groups on the
system and any users associated with them (if all access) or which
ones the current user is in (if limited access).
**REST Request**
::
PUT /sysadm/users
{
"action" : "groupshow"
}
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"name" : "users",
"namespace" : "sysadm",
"args" : {
"action" : "groupshow"
}
}
**Response**
.. code-block:: json
{
"args": {
"_dhcp": {
"gid": "65",
"name": "_dhcp",
"users": [
""
]
},
"_ntp": {
"gid": "123",
"name": "_ntp",
"users": [
""
]
},
"_pflogd": {
"gid": "64",
"name": "_pflogd",
"users": [
""
]
},
"_tss": {
"gid": "601",
"name": "_tss",
"users": [
""
]
},
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: personacryptlistdevs, users
.. _personacryptlistdevs:
Personacrypt List Devices
=========================
:command:`personacrypt_listdevs` will run personacrypt and return any
removeable devices which may be used as PC devices.
**REST Request**
::
PUT /sysadm/users
{
"action" : "personacrypt_listdevs"
}
**WebSocket Request**
.. code-block:: json
{
"namespace" : "sysadm",
"name" : "users",
"id" : "fooid",
"args" : {
"action" : "personacrypt_listdevs"
}
}
**Response**
.. code-block:: json
{
"args": {
"da0": "<SanDisk Cruzer 1.26> 7.5G"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: useradd, users
.. _useradd:
User Add
========
The `useradd` action will add a new user account on the system. There
are a number of required and optional fields to add to the initial
request:
+---------------+----------------+----------------------------------------------------+
| **Name** | **Required/** | **Description** |
| | **Optional** | |
+===============+================+====================================================+
| change | Optional | Sets a time for the password to expire on the new |
| | | account. |
+---------------+----------------+----------------------------------------------------+
| class | Optional | Sets the login class for the user being created. |
| | | |
+---------------+----------------+----------------------------------------------------+
| comment | Optional | This field sets the contents of the psswd GECOS |
| | | field, which normally contains up to four |
| | | comma-separated fields containing the user's full |
| | | name, location, and work and home phone numbers. |
+---------------+----------------+----------------------------------------------------+
| expire | Optional | Sets account expiration date, formatted as either |
| | | a UNIX time in decimal or a date in 'dd-mmm-yyyy' |
| | | format. |
+---------------+----------------+----------------------------------------------------+
| group | Optional | Sets the account's primary group to the given |
| | | group, either by name or group number. |
+---------------+----------------+----------------------------------------------------+
| home_dir | Optional | Sets the account's home directory. |
| | | |
+---------------+----------------+----------------------------------------------------+
| name/user id | Required | A unique string of characters which identifies the |
| (uid) | | new user. |
+---------------+----------------+----------------------------------------------------+
| other_groups | Optional | Sets secondary group memberships for an account. |
| | | |
+---------------+----------------+----------------------------------------------------+
| password | Required | Locks the user account unless a unique string of |
| | | characters is typed into the system first. |
+---------------+----------------+----------------------------------------------------+
| shell | Optional | Configure the user's login to a shell program. |
| | | The full path to the shell program is required. |
+---------------+----------------+----------------------------------------------------+
**REST Request**
::
PUT /sysadm/users
{
"password" : "test",
"name" : "test2",
"action" : "useradd"
}
**WebSocket Request**
.. code-block:: json
{
"name" : "users",
"namespace" : "sysadm",
"id" : "fooid",
"args" : {
"password" : "test",
"name" : "test2",
"action" : "useradd"
}
}
**Response**
.. code-block:: json
{
"args": {
"result": "success"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: userdelete, users
.. _userdelete:
User Delete
===========
The :command:`userdelete` action will remove a user account from the
system. The request requires a "name" field with the desired username
value. The optional "clean_home" field will remove the user's home
directory and all files within it. Its default value is "true".
**REST Request**
::
PUT /sysadm/users
{
"name" : "test",
"action" : "userdelete"
}
**WebSocket Request**
.. code-block:: json
{
"id" : "fooid",
"name" : "users",
"args" : {
"action" : "userdelete",
"name" : "test"
},
"namespace" : "sysadm"
}
**Response**
.. code-block:: json
{
"args": {
"result": "success"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: usermod, users
.. _usermod:
User Mod
========
The :command:`usermod` action is similar to the :command:`useradd`
action, but performs changes to an existing user only. A user with
limited access may modify their own account settings with this command,
but no other user's settings. The field "newname" can also be added to
the request to alter the existing user name.
**REST Request**
::
PUT /sysadm/users
{
"action" : "usermod",
"comment" : "somecomment",
"name" : "test2"
}
**WebSocket Request**
.. code-block:: json
{
"name" : "users",
"namespace" : "sysadm",
"args" : {
"name" : "test2",
"comment" : "somecomment",
"action" : "usermod"
},
"id" : "fooid"
}
**Response**
.. code-block:: json
{
"args": {
"result": "success"
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}
.. index:: usershow, users
.. _usershow:
User Show
=========
:command:`usershow` will display all user accounts registered on the
system, regardless of active/inactive status.
**REST Request**
::
PUT /sysadm/users
{
"action" : "usershow"
}
**WebSocket Request**
.. code-block:: json
{
"namespace" : "sysadm",
"name" : "users",
"id" : "fooid",
"args" : {
"action" : "usershow"
}
}
**Response**
.. code-block:: json
{
"args": {
"_dhcp": {
"change": "0",
"class": "",
"comment": "dhcp programs",
"expire": "0",
"gid": "65",
"home_dir": "/var/empty",
"name": "_dhcp",
"shell": "/usr/sbin/nologin",
"uid": "65"
},
"_ntp": {
"change": "0",
"class": "",
"comment": "NTP Daemon",
"expire": "0",
"gid": "123",
"home_dir": "/var/empty",
"name": "_ntp",
"shell": "/usr/sbin/nologin",
"uid": "123"
}
},
"id": "fooid",
"name": "response",
"namespace": "sysadm"
}

View File

@@ -3,16 +3,12 @@
Getting Started
***************
.. Some intro text here...
Welcome to the SysAdm™ API (application programming interface)
documentation handbook! SysAdm™ is a complex utility with many integral
subsystems and classes, and this handbook will attempt to guide a new
user through the initialization, core features, and intricacies of the
utility.
.. Add some links to docs on websockets and json
This handbook will be heavily utilizing the Websocket specification and
JSON (JavaScript Object Notation) format. For detailed descriptions of
these items, please refer to their respective websites at
@@ -28,22 +24,23 @@ use the authentication class to authenticate itself to obtain access to
the sysadm service. Every authentication class request contains the
following parameters:
+---------------------------------+---------------+------------------------------------------------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+=================================+===============+==============================================================================+
| id | | any unique value for the request; examples include a hash, checksum, or uuid |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| name | auth | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| namespace | rpc | |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
| args | | values vary by type of authentication request |
| | | |
+---------------------------------+---------------+------------------------------------------------------------------------------+
+----------------+------------+---------------------------------------+
| **Parameter** | **Value** | **Description** |
| | | |
+================+============+=======================================+
| id | | any unique value for the request; |
| | | examples include a hash, checksum, |
| | | or uuid |
+----------------+------------+---------------------------------------+
| name | auth | |
| | | |
+----------------+------------+---------------------------------------+
| namespace | rpc | |
| | | |
+----------------+------------+---------------------------------------+
| args | | values vary by type of authentication |
| | | request |
+----------------+------------+---------------------------------------+
There are three options for server authentication: username and password,
token authentication, and pre-registered SSL certifications. SSL
@@ -736,7 +733,8 @@ types using this subsystem.
{
"args": {
"type": "server"
"type": "server",
"hostname": "<hostname>"
},
"id": "fooid",
"name": "response",