such-gitea/wownero-lws
1
0
Fork 1
mirror of https://codeberg.org/wownero/wownero-lws synced 2026-01-09 23:25:16 -08:00
Code Issues Packages Projects Releases Wiki Activity

Add support for admin REST server (#62)

Browse Source
This commit is contained in:
Lee *!* Clagett
2023-02-10 07:18:15 -05:00
committed by Lee *!* Clagett
parent c958ac7963
commit 7b1e1e58f8
13 changed files with 659 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/administration.md
View File

@@ -1,28 +1,91 @@
# Using monero-lws-admin
The `monero-lws-admin` executable is used to administer the database used by
`monero-lws-daemon`. Any number of `monero-lws-admin` instances can run
# monero-lws Administration
The `monero-lws-admin` executable or `--admin-rest-server` option in the
`monero-lws-daemon` executable can be used to administer the database
used by `monero-lws-daemon`. Any number of `monero-lws-admin` instances can run
concurrently with a single `monero-lws-daemon` instance on the same database.
Administration is necessary to authorize new accounts and rescan requests
submitted from the REST API. The admin executable can also be used to list
the contents of the LMDB file for debugging purposes.
# Basics
# monero-lws-admin
The `monero-lws-admin` utility is structured around command-line arguments with
JSON responses printed to `stdout`. Each administration command takes arguments
by position - the design makes it potentially compatible with a JSON or MsgPack
array (as used in JSON-RPC, etc). Every available administration command and
required+optional arguments are listed when the `--help` flag is given to the
executable.
by position. Every available administration command and required+optional
arguments are listed when the `--help` flag is given to the executable.
The [`jq`](https://stedolan.github.io/jq/) utility is recommended if using
`monero-lws-admin` in a shell environment. The `jq` program can be used for
indenting the output to make it more readable, and can be used to
search+filter the JSON output from the command.
# Admin REST API
The `monero-lws-daemon` can be started with 1+ `--admin-rest-server` parameters
that specify a listening location for admin REST clients. By default, there is
no admin REST server and no available admin accounts.
An admin REST server can be merged with a regular REST server if path prefixes
are specified, such as
`--rest-server https://0.0.0.0:8443/basic --admin-rest-server https://0.0.0.0:8443/admin`.
This will start a server listening on one port, 8443, and requires clients to
specify `/basic/command` or `/admin/admin_command` when making a
request.
An admin account account can be created via `monero-lws-admin create_admin`
_only_ (this command is not available via REST for security purposes). The
`key` value returned in the `create_admin` JSON object becomes the `auth`
parameter in the admin REST API. A new admin account is put into the
`hidden` state - the account is _not_ scanned for transactions and is _not_
available to the normal REST API, but is available to the admin REST API.
Running `monero-lws-admin list_admin` will display all current admin
accounts, and their current state ("active", "inactive", or "hidden"). If
an admin account needs to be revoked, use the `modify_account` command
to put the account into the "inactive" state. Deleting accounts is not
currently supported.
Every admin REST request must be a `POST` that contains a JSON object with
an `auth` field and an optional `params` field:
```json
{
"auth":"...",
"params":{...}
}
```
where the `params` object is specified below.
## Commands
A subset of admin commands are available via admin REST API - the remainder
are initially omitted for security purposes. The commands available via REST
are:
* **accept_requests**: `{"type": "import"|"create", "addresses":[...]}`
* **add_account**: `{"address": ..., "key": ...}`
* **list_accounts**: `{}`
* **list_requests**: `{}`
* **modify_account_status**: `{"status": "active"|"hidden"|"inactive", "addresses":[...]}`
* **reject_requests**: `{"type": "import"|"create", "addresses":[...]}`
* **rescan**: `{"height":..., "addresses":[...]}`
where the listed object must be the `params` field above.
# Examples
## Admin REST API
```json
{
"auth":"6d732245002a9499b3842c0a7f9fc6b2d657c77bd612dbefa4f7f9357d08530a",
"params":{
"status": "inactive",
"addresses": ["9sAejnQ9EBR1111111111111111111111111111111111AdYmVTw2Tv6L9KYkHjJ2wd737ov8ZL5QU7CJ4zV6basGP9fyno"]
}
}
```
will put the listed address into the "inactive" state.
## monero-lws-admin
**List every active Monero address on a newline:**
```bash
monero-lws-admin list_accounts | jq -r '.active | .[] | .address'