From 65a9b2dc88c4756f10c8287347d33b01bb1ec9c4 Mon Sep 17 00:00:00 2001
From: Thien-Thi Nguyen <ttn@gnuvola.org>
Date: Wed, 26 Jan 2022 06:14:21 -0500
Subject: New manpage: libeufin-nexus(1)

* manpages/libeufin-nexus.1.rst: New file.
* conf.py (man_pages): Add entry for libeufin-nexus.

This partially addresses: <https://bugs.gnunet.org/view.php?id=7147>
---
 manpages/libeufin-nexus.1.rst | 150 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 manpages/libeufin-nexus.1.rst

(limited to 'manpages')

diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst
new file mode 100644
index 00000000..d1a0698e
--- /dev/null
+++ b/manpages/libeufin-nexus.1.rst
@@ -0,0 +1,150 @@
+libeufin-nexus(1)
+#################
+
+.. only:: html
+
+   Name
+   ====
+
+   **libeufin-nexus** - Sevice to interface to various bank access APIs
+
+
+Synopsis
+========
+
+**libeufin-nexus**
+[**-h** | **--help**]
+[**--version**]
+COMMAND [ARGS...]
+
+Commands: serve, superuser, parse-camt, reset-tables
+
+
+Description
+===========
+
+**libeufin-nexus** is a program that provides a service to interface to
+various bank access APIs, using JSON as the response format.
+It maintains state in its own private database.
+You interact with it through HTTP
+requests either over the network or via a Unix domain socket.
+Related program **libeufin-cli** is the preferred front end
+for that mode of operation.
+There is also a mode where **libeufin-nexus** accepts commands directly,
+useful for doing administrative tasks.
+
+Its options are as follows:
+
+**-h** \| **--help**
+   Print short help on options.
+
+**–version**
+   Print version information.
+
+The interaction model is as follows:
+
+- Configure the nexus with command ``superuser``.
+
+- Start the HTTP server with command ``serve``.
+  Let this run in a shell, writing logs to stderr.
+
+- Interact with **libeufin-nexus**.
+
+- When finished, interrupt the ``serve`` process and clean up with command
+  ``reset-tables``.
+
+The following sections describe each command in detail.
+
+
+superuser
+---------
+
+This command adds a superuser, or changes the password.
+It takes argument ``USERNAME``.
+Option ``--password TEXT`` specifies the password.
+If omitted, **libeufin-nexus** will query interactively for it.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-nexus superuser joe
+
+This creates superuser ``joe`` and interactively queries for the password.
+
+
+parse-camt
+----------
+
+This command parses a camt file and displays the result to stdout.
+It takes argument ``FILENAME``, which names a file in CAMT format.
+Parsing may also display log information to stderr.
+The normal log level is ``DEBUG``.
+To change it, use ``--log-level LEVEL``, where ``LEVEL`` is one of:
+``ERROR``, ``WARN``, ``INFO``, ``DEBUG``, ``TRACE``.
+
+For example:
+
+.. code-block:: console
+
+  $ libeufin-nexus parse-camt camt53-gls-style-0.xml
+  {
+    "transactions" : [ {
+      "amount" : "EUR:2.35",
+      "creditDebitIndicator" : "DBIT",
+      ...
+    } ]
+  }
+
+
+serve
+-----
+
+This command starts the HTTP server, listening on port 5001.
+To use a different port, use option ``--port INT``.
+To listen, instead, on a Unix domain socket,
+use option ``--with-unix-socket PATH``.
+When both ``--port`` and ``--with-unix-socket`` are given,
+``--with-unix-socket`` takes precedence.
+
+The process runs in the foreground, writing its logs to standard error.
+The normal log level is ``DEBUG``.
+To change it, use ``--log-level LEVEL``, where ``LEVEL`` is one of:
+``ERROR``, ``WARN``, ``INFO``, ``DEBUG``, ``TRACE``.
+
+Before invoking ``serve``, the following environment variable needs to be set:
+
+``LIBEUFIN_NEXUS_DB_CONNECTION``
+   This specifies the database **libeufin-nexus** uses to maintain state.
+   Currently, both Sqlite and PostgreSQL are supported.
+   (Only one needs to be specified.)
+   Examples:
+
+   - ``jdbc:sqlite:/tmp/libeufin-nexus.db``
+   - ``jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret``
+
+Normally, the ``serve`` command runs until interrupted.
+When run in a shell, you can use ``Control-C`` for that.
+
+
+reset-tables
+------------
+
+This command drops all the tables in the internal database.
+(The next time the tables are needed, **libeufin-nexus** creates them
+again, automatically.)
+
+It should only be used when the nexus is quiescent.
+
+
+See Also
+========
+
+.. TODO: libeufin-sandbox(1), libeufin-cli(1).
+
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
-- 
cgit v1.2.3