From a672c051127afbfedfc6d00f0770fc64d784112a Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 9 Sep 2023 00:03:09 -0400 Subject: [PATCH] Finish moving over current Administrator API documentation. --- docs/user/admin/config.md | 42 ++++ docs/user/admin/proc.md | 49 ++++ docs/user/admin/stats.md | 24 ++ man/man7/telodendria-admin.7 | 421 ----------------------------------- 4 files changed, 115 insertions(+), 421 deletions(-) create mode 100644 docs/user/admin/config.md create mode 100644 docs/user/admin/proc.md create mode 100644 docs/user/admin/stats.md delete mode 100644 man/man7/telodendria-admin.7 diff --git a/docs/user/admin/config.md b/docs/user/admin/config.md new file mode 100644 index 0000000..0466403 --- /dev/null +++ b/docs/user/admin/config.md @@ -0,0 +1,42 @@ +# Administrator API: Configuration + +As mentioned in [Setup](../setup.md), Telodendria's configuration is +intended to be managed via the configuration API. Consult the +[Configuration](../config.md) document for a complete list of supported +configuration options. This document simply describes the API used to +update the configuration. + +## API Endpoints + +### **GET** `/_telodendria/admin/config` + +Retrieve the current configuration. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The current configuration was successfully retrieved.| + +### **POST** `/_telodendria/admin/config` + +Installs a new configuration. This endpoint validates the request body, +ensuring it is a proper configuration, then it replaces the existing +configuration with the new one. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The new configuration was successfully installed.| + +#### 200 Response Format + +| Field | Type | Description | +|-------|------|-------------| +| `restart_required` | `Boolean` | Whether or not the process needs to be restarted to finish applying the configuration. If this is `true`, then the restart endpoint should be used at a convenient time to apply the configuration. + diff --git a/docs/user/admin/proc.md b/docs/user/admin/proc.md new file mode 100644 index 0000000..4db33ec --- /dev/null +++ b/docs/user/admin/proc.md @@ -0,0 +1,49 @@ +# Administrator API: Process Control + +This document describes the administrator APIs that allow a server +administrator to manage the Telodendria process itself. + +## API Endpoints + +### **POST** `/_telodendria/admin/restart` + +Restart the Telodendria daemon cleanly. This endpoint will respond +immediately after signaling to the daemon that it should be restarted +as soon as possible. Note that the restart wmay not happen +instantaneously, as Telodendria will finish processing all current +requests before restarting. Also note that this is not a true restart; +the process does not exit and restart, rather, Telodendria simply tears +down all its state and then jumps back to the beginning of its code and +starts over. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The restart request was successfully sent.| + +On success, this endpoint simply returns an empty JSON object. + +### **POST** `/_telodendria/admin/shutdown` + +Shut down the Telodendria process cleanly. This endpoint will respond +immediately after signalling to the daemon that it should be shut +down as soon as possible. Note that the shutdown may not happen +instantaneously, as Telodendria will finish processing all current +requests before shutting down. Also note that once shut down, Telodendria +may be automatically restarted by the system's service manager. +Otherwise, it will have to be manually restarted. This is a true +shutdown; the Telodendria process exits as soon as possible. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +|---------------|-------------| +| 200 | The shutdown request was successfully sent.| + +On success, this endpoint simply returns an empty JSON object. + diff --git a/docs/user/admin/stats.md b/docs/user/admin/stats.md new file mode 100644 index 0000000..af421f8 --- /dev/null +++ b/docs/user/admin/stats.md @@ -0,0 +1,24 @@ +# Administrator API: Server Statistics + +The administrator API allows users with the proper privileges to get +information about how the server process is performing. + +## API Endpoints + +### **GET** `/_telodendria/admin/stats` + +Retrieve basic statistics about the currently running Telodendria +process. + +| Requires Token | Rate Limited | +|----------------|--------------| +| Yes | Yes | + +| Response Code | Description | +| 200 | The server statistics were successfully retrieved.| + +#### 200 Response Format + +| Field | Type | Description | +| `memory_allocated` | `Integer` | The total amount of memory allocated, measured in bytes.| +| `version` | `String` | The current version of Telodendria.| diff --git a/man/man7/telodendria-admin.7 b/man/man7/telodendria-admin.7 deleted file mode 100644 index 2fd0964..0000000 --- a/man/man7/telodendria-admin.7 +++ /dev/null @@ -1,421 +0,0 @@ -.Dd $Mdocdate: August 9 2023 $ -.Dt TELODENDRIA-ADMIN 7 -.Os Telodendria Project -.Sh NAME -.Nm telodendria-admin -.Nd Administrator API documention. -.Sh DESCRIPTION -.Pp -Telodendria provides an administrator API that allows for administrator control -over the homeserver. This includes profiling and examining the state of Telodendria, -as well as managing users and media. -.Pp -Like Synapse, Telodendria supports designating specific users as administrators. -However, unlike Synapse, it uses a more finely-grained privilege model that allows -a server administrator to designate specific administration tasks to other users -while not compromising and granting them full administrative access to the server. -.Pp -To authenticate with the administrator API, simply use a regular -access token. -.Ss Privileges -.Pp -Here are all of the privileges a local user can have. Unless otherwise specified, -these privileges only grant access to certain parts of the administrator API; the -regular Matrix API is unaffected. -.Bl -tag -width -Ds -.It Dv DEACTIVATE -Allows a user to deactivate any other local users. -.It Dv ISSUE_TOKENS -Allows a user to create, modify, and delete registration tokens. -.It Dv CONFIG -Allows a user to modify the Telodendria server daemon's configuration. -.It Dv GRANT_PRIVILEGES -Allows a user to modify his or her own privileges or the privileges of other -local users. -.It Dv ALIAS -Allows a user to modify room aliases created by other users. By default, users -can only manage their own room aliases, but an administrator may wish to take -over an alias or remove an offensive alias. -.It Dv PROC_CONTROL -Allows a user to get statistics on the running process, as well as shutdown and -restart the Telodendria daemon itself. Typically this will pair well with -.Dv CONFIG , -because there are certain configuration options that require the process to be -restarted. -.El -.Pp -There is also a special ``pseudo-privilege'': -.Bl -tag -width Ds -.It Dv ALL -Grants a user all of the aforementioned privileges, as well as privileges that -do not yet exist. That is, if an update to Telodendria adds more privileges, -users with this privilege will automatically gain those new privileges in -addition to having all of the existing privileges. -.Pp -This privilege should only be used with fully-trusted users. It is typical for -a server administrator to not fully trust anyone else, and be the only one that -holds an account with this privilege level. -.El -.Sh API ENDPOINTS -.Pp -The following API endpoints are implemented for the installed version of -Telodendria. -.Pp -Unless otherwise indicated, HTTP response codes that are not 200 Ok -will be accompanied by a standard Matrix API error. Consult the Matrix specification -for the format of these errors. The following error conditions are assumed to be -possible for all of the endpoints listed here: -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -400;T{ -The user is not authenticated, did not provide a valid JSON object, -or provided a JSON object with invalid parameters. -T} -403;T{ -The user does not have the privileges necessary to carry out the -specified action. -T} -500;T{ -A fatal server error occured. Check the logs for more information. -T} -.TE -.Ss Sy GET No /_telodendria/admin/privileges/[localpart] -.Pp -Retrieve the permissions for a user. If the localpart is -omitted, then retrieve the privileges for the user that owns -the access token being used. Note that the owner of the -access token must have the -.Dv GRANT_PRIVILEGES -privilege. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The privileges were successfully retrieved. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy POST No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by replacing the -privileges array with the one specified in the request. -Like the -.Sy GET -version of this endpoint, the localpart can be omitted to -operate on the user that owns the access token. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The privileges were successfully replaced. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy PUT No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by adding the privileges -specified in the request to the user's existing privileges. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The requested privileges were successfully added. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy DELETE No /_telodendria/admin/privileges/[localpart] -.Pp -Update the privileges of a local user by removing the privileges -specified in the request from the user's existing privileges. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The requested privileges were successfully removed. -T} -.TE -.Pp -Request Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -privileges;Array;T{ -An array of privileges, as described above. The -privileges are represented as strings in JSON. -T} -.TE -.Ss Sy POST No /_telodendria/admin/config -.Pp -Installs a new configuration. It validates the request body, ensuring it is a -proper configuration, then replaces the existing configuration with the new one. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token; Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The new configuration was successfully installed. -T} -.TE -.Pp -Consult the -.Xr telodendria-config 7 -manual page for a full description of the configuration object that should -be submitted. That page lists all the fields, and notes which ones are -required. -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -restart_required;Boolean;T{ -Whether or not the process needs to be restarted to finish applying the -configuration. If this is true, the restart endpoint may be used. -T} -.TE -.Ss Sy GET No /_telodendria/admin/config -.Pp -Retrieve the current configuration. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The current configuration was successfully retrieved. -T} -.TE -.Pp -Consult the -.Xr telodendria-config 7 -manual page for a full description of the configuration object that -is returned. Note that this is the same object that was submitted -using the -.Sy POST -version of this endpoint, otherwise it is the default configuration. -.Ss Sy GET No /_telodendria/admin/stats -.Pp -Retrieve statistics about the currently running Telodendria process. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The server statistics were successfully retrieved. -T} -.TE -.Pp -200 Response Format: -.TS -tab(;) allbox expand; -lfB lfB lfB -l l l. -Field;Type;Description -memory_allocated;Integer;T{ -The total amount of memory allocated, measured in bytes. -T} -version;String;T{ -The current version of Telodendria. -T} -.TE -.Ss Sy POST No /_telodendria/admin/restart -.Pp -Restart the Telodendria daemon cleanly. This endpoint will respond immediately -after signaling to the daemon that it should be restarted as soon as possible. -Note that the restart may not happen instantaneously, as Telodendria will finish -processing all current requests before restarting. Also note that this is not a -``true'' restart; the process does not exit and restart, rather, Telodendria -simply tears down its state, and then jumps back to the beginning of its code -and starts over. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The restart request was successfully sent. -T} -.TE -.Pp -On success, this endpoint simply returns an empty JSON object. -.Ss Sy POST No /_telodendria/admin/shutdown -.Pp -Shut down the Telodendria process cleanly. This endpoint will respond immediately -after signaling to the daemon that it should be shut down as soon as possible. -Note that the shutdown may not happen instantaneously, as Telodnedria will -finish processing all current requests before shutting down. Also note that once -shut down, Telodendria may be automatically restarted by the system's service -manager, otherwise, it will have to be manually restarted. This is a ``true'' -shutdown, the Telodendria process exits as soon as possible. -.Pp -.TS -tab(;) allbox expand; -lfB lfB -l l. -Requires Token;Rate Limited -Yes;Yes -.TE -.TS -tab(;) allbox expand; -lfB lfB -l l. -Response Code;Description -200;T{ -The shutdown request was successfully sent. -T} -.TE -.Pp -On success, this endpoint simply returns an empty JSON object. -.Sh SEE ALSO -.Xr telodendria-config 7 , -.Xr telodendria-setup 7