diff --git a/api/classes/beadm.rst b/api/classes/beadm.rst index 1df903b..3a65226 100644 --- a/api/classes/beadm.rst +++ b/api/classes/beadm.rst @@ -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** | diff --git a/api/classes/updates.rst b/api/classes/updates.rst index b3e67cf..ba2c7a1 100644 --- a/api/classes/updates.rst +++ b/api/classes/updates.rst @@ -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" : "", "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" : "", "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" } } - } \ No newline at end of file + } + +.. 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" + } + } + } diff --git a/api/classes/users.rst b/api/classes/users.rst new file mode 100644 index 0000000..a0ae50e --- /dev/null +++ b/api/classes/users.rst @@ -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" : "" + }, + "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": " 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" + } diff --git a/api/connection.rst b/api/connection.rst index d67bf3b..46ed8a4 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -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": "" }, "id": "fooid", "name": "response",