diff options
Diffstat (limited to 'manpages/libeufin-nexus.1.rst')
| -rw-r--r-- | manpages/libeufin-nexus.1.rst | 182 |
1 files changed, 102 insertions, 80 deletions
diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index 792c1de6..5eb42cab 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -6,7 +6,7 @@ libeufin-nexus(1) Name ==== - **libeufin-nexus** - Service to interface to various bank access APIs + **libeufin-nexus** - EBICS client. Synopsis @@ -17,21 +17,14 @@ Synopsis [**--version**] COMMAND [ARGS...] -Commands: serve, superuser, parse-camt, reset-tables +Subcommands: **dbinit**, **ebics-setup**, **ebics-submit**, **ebics-fetch**, **config** 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. +various bank access APIs Its options are as follows: @@ -43,108 +36,137 @@ Its options are as follows: 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``. +In order to operate any EBICS communication with ``libeufin-nexus``, it is necessary to setup EBICS access via the ``ebics-setup`` subcommand. Setting the access means to share the client keys with the bank and downloading the bank keys. After a successful setup, the subcommands ``ebics-submit`` and ``ebics-fetch`` can be run to respectively send payments and download the bank account history. The following sections describe each command in detail. +ebics-setup +----------- -superuser ---------- +This command creates the client keys, if they aren't found already on the disk, and sends them to the bank if they were not sent yet. In case of sending, it ejects the PDF document that contains the keys fingerprints, so that the user can send it to the bank to confirm their keys. The process continues by checking if the bank keys exist already on disk, and proceeds with downloading them in case they are not. It checks then if the bank keys were accepted by the user; if yes, the setup terminates, otherwise it interactively asks the user to mark the keys as accepted. By accepting the bank keys, the setup terminates successfully. -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. +Its options are as follows: -For example: +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--force-keys-resubmission** + Resubmits the client keys. If no keys were found, it creates and submits them. +**--auto-accept-keys** + Accepts the bank keys without interactively asking the user. +**--generate-registration-pdf** + Generates the PDF with the client keys fingerprints, if the keys have the submitted state. That's useful in case the PDF went lost after the first submission and the user needs a new PDF. -.. code-block:: console - $ libeufin-nexus superuser joe +dbinit +------ -This creates superuser ``joe`` and interactively queries for the password. +This subcommand defines the database schema for Nexus. It is mandatory to run this command before invoking the ``ebics-submit`` or ``ebics-fetch`` subcommands. +Its options are as follows: -parse-camt ----------- +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**-r** \| **--reset** + If present, deletes any database table (WARNING: potential data loss) -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: +ebics-submit +------------ -.. code-block:: console +This subcommand submits any initiated payment that was not already sent to the bank. In the current version, initiated payments may come from a cash-out operation or from a bounced incoming payment. ebics-submit is Taler friendly, therefore bounced payments are those that do not contain a valid subject to start a Taler withdrawal. Cash-out operations come from a tightly integrated bank that offers their customers to convert their currency to the currency whose the EBICS subscriber bank account is tied to. - $ libeufin-nexus parse-camt camt53-gls-style-0.xml - { - "transactions" : [ { - "amount" : "EUR:2.35", - "creditDebitIndicator" : "DBIT", - ... - } ] - } +Its options are as follows: +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + Uploaded documents will be stored *before* being submitted to the bank. This directory would contain several directories, each named after the ``YYYY-MM-DD/submit`` format. The pain.001 file would then be named in the following schema: ``$microseconds_pain.001.xml``. +**--transient** + This flag causes the command to check the database and submit only once, and then return. -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. +ebics-fetch +----------- -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``. +This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that show up in the downloaded records. -Before invoking ``serve``, the following environment variable needs to be set: +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: -``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: +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``report``: Account intraday reports, retrieves the history of confirmed debits and credits. +* ``statement``: Account statements, retrieves the history of confirmed debits and credits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. - - ``jdbc:sqlite:/tmp/libeufin-nexus.db`` - - ``jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret`` +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--debug-ebics** *SAVEDIR* + Log EBICS content at SAVEDIR. + Downloaded documents will be stored *before* being ingested in the database. This directory would contain several directories, each named after the ``YYYY-MM-DD/fetch`` format. The stored files would then be named after the following schema: ``$microseconds_$filename``. Exception to this naming scheme are the HAC responses, since they do not get any filename assigned by the ZIP archive (they are sent unzipped). Their naming scheme is: ``$microseconds_HAC_response.pain.002.xml``. +**--transient** + This flag causes the command to perform one download and return. +**--pinned-start** + Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents. The latest timestamp is always the current time. -Normally, the ``serve`` command runs until interrupted. -When run in a shell, you can use ``Control-C`` for that. +serve +----- +This command starts the HTTP server. -reset-tables ------------- +Its options are as follows: -This command drops all the tables in the internal database. -(The next time the tables are needed, **libeufin-nexus** creates them -again, automatically.) +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--check** + This flag causes the command to check whether an API is in use (if it's useful to start the HTTP server) and to output 0 if at least one API is enabled, otherwise 1. -It should only be used when the nexus is quiescent. +initiate-payment +---------------- +This subcommand initiates an outgoing payment. The pending payment is stored in the database and will be performed the next time ``ebics-submit`` run. -See Also -======== +It takes one argument, the creditor IBAN payto URI, which must contain a 'receiver-name' and may contain an 'amount' and a 'message' if they have not been defined using CLI options. -.. TODO: libeufin-sandbox(1), libeufin-cli(1). +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--amount** *AMOUNT* + The amount to transfer, payto 'amount' parameter takes the precedence +**--subject** *TEXT* + The payment subject, payto 'message' parameter takes the precedence +**--request-uid** *TEXT* + The payment request UID, will be randomly generated if missing. + +.. include:: ../frags/libeufin-config-cli.rst + +SEE ALSO +======== +libeufin-nexus.conf(5) Bugs ==== -Report bugs by using https://bugs.taler.net or by sending electronic -mail to <taler@gnu.org>. +Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>. |