diff options
Diffstat (limited to 'manpages')
| -rw-r--r-- | manpages/libeufin-bank.conf.5.rst | 3 | ||||
| -rw-r--r-- | manpages/libeufin-cli.1.rst | 1006 | ||||
| -rw-r--r-- | manpages/libeufin-nexus.1.rst | 22 | ||||
| -rw-r--r-- | manpages/libeufin-nexus.conf.5.rst | 61 | ||||
| -rw-r--r-- | manpages/libeufin-sandbox.1.rst | 227 | ||||
| -rw-r--r-- | manpages/taler.conf.5.rst | 189 |
6 files changed, 263 insertions, 1245 deletions
diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst index e00bab92..ce00f0fa 100644 --- a/manpages/libeufin-bank.conf.5.rst +++ b/manpages/libeufin-bank.conf.5.rst @@ -47,6 +47,9 @@ X_TALER_BANK_PAYTO_HOSTNAME NAME Bank display name, used in webui and TAN messages. Default to ``Taler Bank`` if not specified. +BASE_URL + The advertised base URL + DEFAULT_DEBT_LIMIT Default debt limit for newly created accounts. Defaults to ``CURRENCY:0`` if not specified. diff --git a/manpages/libeufin-cli.1.rst b/manpages/libeufin-cli.1.rst deleted file mode 100644 index 755c8b45..00000000 --- a/manpages/libeufin-cli.1.rst +++ /dev/null @@ -1,1006 +0,0 @@ -libeufin-cli(1) -############### - -.. only:: html - - Name - ==== - - **libeufin-cli** - Interact with LibEuFin Sandbox and Nexus - - -Synopsis -======== - -**libeufin-cli** -[**-h** | **--help**] -[**--version**] -COMMAND [ARGS...] - -Commands: accounts, connections, facades, permissions, sandbox, users - - -Description -=========== - -**libeufin-cli** is the user interface program to interact -with **libeufin-sandbox** and **libeufin-nexus** when they are -operating as HTTP servers, listening on localhost ports. -Normally, you invoke them with their respective ``serve`` commands, -and in a separate shell, use **libeufin-cli** to send requests -and receive responses from them. - -The interaction model is as follows: - -- (Optionally) Start the sandbox. - -- Start the nexus. - -- Use **libeufin-cli** to interact with them. - You can manage users and permissions, bank accounts, "facades", - transactions, and connections between the various systems. - -For **libeufin-cli** to be able to communicate with **libeufin-sandbox**, -the following environment variables need to be set: - -``LIBEUFIN_SANDBOX_USERNAME`` - This should normally be ``admin``. - -``LIBEUFIN_SANDBOX_PASSWORD`` - This is the same password chosen when the sandbox was started. - -``LIBEUFIN_SANDBOX_URL`` - This is ``http://localhost:PORT``, where ``PORT`` is the - same port chosen when the sandbox was started. - This URL can also be specified with the ``--sandbox-url URL`` - option to the ``sandbox`` command (see below). - If both are given, the ``--sandbox-url`` option takes precedence. - -For **libeufin-cli** to be able to communicate with **libeufin-nexus**, -the following environment variables need to be set: - -``LIBEUFIN_NEXUS_USERNAME`` - For some operations (such as ``users create``), this must be the - same username chosen by the ``libeufin-nexus superuser`` command. - -``LIBEUFIN_NEXUS_PASSWORD`` - This is the password associated with the username. - -``LIBEUFIN_NEXUS_URL`` - This is ``http://localhost:PORT``, where ``PORT`` is the - same port chosen when the nexus was started. - -Of the six commands, the ``sandbox`` command talks to the sandbox, -while the other five commands talk to the nexus. -The following sections describe each command and their subcommands in detail. - - -sandbox -------- - -The ``libeufin-cli sandbox`` command is for managing the sandbox process -started by ``libeufin-sandbox serve``. -It takes one option, ``--sandbox-url URL``, to be specified before -the subcommands and their arguments. -This URL can also be specified with the ``LIBEUFIN_SANDBOX_URL`` -environment variable (see above). -If both are given, the ``--sandbox-url`` option takes precedence. - -The following subcommands are available: bankaccount, check, demobank, -ebicsbankaccount, ebicshost, ebicssubscriber. - -The first command to use is ``check``, -followed by ``ebicshost``, ``ebicssubscriber``, -and ``ebicsbankaccount``, to configure the basic system. - -You can then use the ``bankaccount`` command to generate (simulated) -transaction traffic. - -After that, the ``demobank`` command and its subcommands -provide the same access to the API that Nexus itself uses. -You normally do not need to use those commands directly. - - -sandbox check -------------- - -The ``check`` command attempts a simple aliveness check by -contacting the sandbox and displaying its returned message. -If all goes well, you should see something like: - -.. code-block:: console - - $ libeufin-cli sandbox check - Hello, this is the Sandbox - - -sandbox ebicshost ------------------ - -The ``ebicshost`` command manages EBICS hosts. -It has two subcommands: create and list. - -sandbox ebicshost create -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicshost create`` command creates a EBICS host. -It takes one option, ``--host-id ID``, where ``ID`` is used to -identify that host for all future commands. - -sandbox ebicshost list -^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicshost list`` command lists the hosts in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicshost create --host-id testhost - $ libeufin-cli sandbox ebicshost list - { - "ebicsHosts" : [ "testhost" ] - } - -Here, the ``ID`` is ``testhost``. - - -sandbox ebicssubscriber ------------------------ - -The ``ebicssubscriber`` command manages EBICS subscribers. -It has two subcommands: create and list. - -sandbox ebicssubscriber create -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -NB: This command is deprecated and will be removed at some point. -See ``sandbox demobank new-ebicssubscriber`` (below) for its replacement. - -The ``ebicssubscriber create`` command creates a EBICS subscriber. -It takes three options, all of which are required: - -:: - - --host-id TEXT Ebics host ID - --partner-id TEXT Ebics partner ID - --user-id TEXT Ebics user ID - -The host ID should be the same one specified in ``ebicshost create`` -(see above). - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicssubscriber create \ - --host-id testhost \ - --partner-id partner01 \ - --user-id user01 - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example (see above). - -sandbox ebicssubscriber list -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicssubscriber list`` command lists the EBICS subscribers -in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicssubscriber list - { - "subscribers" : [ { - "hostID" : "testhost", - "partnerID" : "partner01", - "userID" : "user01", - "systemID" : null, - "demobankAccountLabel" : "not associated yet" - } ] - } - -Note that the output reflects the subscriber created in -the ``ebicssubscriber create`` example (see above). - - -sandbox ebicsbankaccount ------------------------- - -The ``ebicsbankaccount`` command manages EBICS bank accounts. -It has one subcommand: create. -(To list accounts, see ``sandbox bankaccount`` below.) - -sandbox ebicsbankaccount -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicsbankaccount create`` command takes several options, all required: - -:: - - --iban TEXT IBAN - --bic TEXT BIC - --person-name TEXT bank account owner name - --account-name TEXT label of this bank account - --ebics-user-id TEXT user ID of the Ebics subscriber - --ebics-host-id TEXT host ID of the Ebics subscriber - --ebics-partner-id TEXT partner ID of the Ebics subscriber - -At this time, although the ``--person-name`` option is required, -the sandbox does not remember the option value. -(When queried, it displays "Bank account owner's name" instead. -See ``sandbox bankaccount`` below.) -For the sandbox, the important value is the ``--account-name`` option. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicsbankaccount create \ - --iban DE18500105172929531888 \ - --bic INGDDEFFXXX \ - --person-name "Jane Normal" \ - --account-name testacct01 \ - --ebics-host-id testhost \ - --ebics-user-id user01 \ - --ebics-partner-id partner01 - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example, and that ``user01`` and ``partner01`` are the same as in the -``ebicssubscriber create`` example (see above). - - -sandbox bankaccount -------------------- - -The ``bankaccount`` command manages bank accounts. -It has several subcommands: list, generate-transactions, -simulate-incoming-transaction, transactions. - -sandbox bankaccount list -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount list`` command lists the bank accounts in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount list - [ { - "label" : "bank", - "name" : "Bank account owner's name", - "iban" : "DE370758", - "bic" : "SANDBOXX" - }, { - "label" : "testacct01", - "name" : "Bank account owner's name", - "iban" : "DE18500105172929531888", - "bic" : "INGDDEFFXXX" - } ] - -Note that ``testacct01``, ``DE18500105172929531888``, and ``INGDDEFFXXX`` -are the same as specified in the ``ebicsbankaccount create`` example -(see above). - -sandbox bankaccount generate-transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The remaining ``bankaccount`` commands deal with transactions -to and from the bank accounts. - -The ``bankaccount generate-transactions`` command generates -test transactions. -It takes one arg, the account label. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount generate-transactions testacct01 - -Note that ``testacct01`` is the account label shown in the ``bankaccount -list`` example (see above). - -sandbox bankaccount simulate-incoming-transaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount simulate-incoming-transaction`` books an -incoming payment in the sandbox. -It takes one arg, the account label, and several options. - -:: - - --debtor-iban TEXT IBAN sending the payment - --debtor-bic TEXT BIC sending the payment - --debtor-name TEXT name of the person who is sending the payment - --amount TEXT amount, no currency - --subject TEXT payment subject - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction - testacct01 \ - --debtor-iban DE06500105174526623718 \ - --debtor-bic INGDDEFFXXX \ - --debtor-name "Joe Foo" \ - --subject "Hello World" \ - --amount 10.50 - -Note that ``testacct01`` is the same as in previous examples (see above), -and that ``10.50`` is in ``X.Y`` format. - -sandbox bankaccount transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount transactions`` command lists transactions. -It takes one arg, the account label. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount transactions testacct01 - { - "payments" : [ { - "account_label" : "testacct01", - "creditor_iban" : "DE18500105172929531888", - "creditor_bic" : "INGDDEFFXXX", - "creditor_name" : "Creditor Name", - "debtor_iban" : "DE64500105178797276788", - "debtor_bic" : "DEUTDEBB101", - "debtor_name" : "Max Mustermann", - "amount" : "5", - "currency" : "EUR", - "subject" : "sample transaction DILWBJHL", - "date" : "Wed, 26 Jan 2022 09:03:44 GMT", - "credit_debit_indicator" : "credit", - "account_servicer_reference" : "DILWBJHL", - "paymentInformationId" : null - }, { - "account_label" : "testacct01", - "creditor_iban" : "DE64500105178797276788", - "creditor_bic" : "DEUTDEBB101", - "creditor_name" : "Max Mustermann", - "debtor_iban" : "DE18500105172929531888", - "debtor_bic" : "INGDDEFFXXX", - "debtor_name" : "Debitor Name", - "amount" : "12", - "currency" : "EUR", - "subject" : "sample transaction N7JSY17B", - "date" : "Wed, 26 Jan 2022 09:03:44 GMT", - "credit_debit_indicator" : "debit", - "account_servicer_reference" : "N7JSY17B", - "paymentInformationId" : null - }, { - "account_label" : "testacct01", - "creditor_iban" : "DE18500105172929531888", - "creditor_bic" : "INGDDEFFXXX", - "creditor_name" : "Creditor Name", - "debtor_iban" : "DE06500105174526623718", - "debtor_bic" : "INGDDEFFXXX", - "debtor_name" : "Joe Foo", - "amount" : "10.50", - "currency" : "EUR", - "subject" : "Hello World", - "date" : "Wed, 26 Jan 2022 09:04:31 GMT", - "credit_debit_indicator" : "credit", - "account_servicer_reference" : "sandbox-6UI2J3636J9EESXO", - "paymentInformationId" : null - } ] - } - -Note that ``testacct01`` is the same as in previous examples (see above), -and that the generated transactions from previous examples are listed, -as well. - - -sandbox demobank ----------------- - -The ``demobank`` command provides an interface to the Access API, -which includes three commands: register, info, new-transaction. -There is also a fourth ``demobank`` command, new-ebicssubscriber, -that does not use the Access API. - -For all ``demobank`` commands, the sandbox URL *must* specify which -*one* bank the command applies to in the base URL. -Note that this URL cannot be used with other sandbox commands. -In other words: - -``--sandbox-url http://localhost:5016/demobanks/default`` - This base URL can be used for commands: - - - sandbox demobank register - - sandbox demobank info - - sandbox demobank new-ebicssubscriber - - sandbox demobank new-transaction - - It specifies the ``default`` demobank. - -``--sandbox-url http://localhost:5016`` - This base URL can be used for all other sandbox commands. - -In the following examples, the base URL will be explicitly shown with -the ``--sandbox-url`` option for the ``demobank`` commands. - -sandbox demobank register -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank register`` command registers a new bank account. -Note that the username will be both the username to login at -the bank and the bank account label. -It takes the username and password from the -``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` -environment variables. -The username *need not be* ``admin``. - -For example: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=jrluser - $ export LIBEUFIN_SANDBOX_PASSWORD=easy - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank register - -sandbox demobank info -^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank info`` command returns basic information on a bank account. -It takes option ``--bank-account NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank info --bank-account jrluser - { - "balance" : { - "amount" : "EUR:100", - "credit_debit_indicator" : "credit" - }, - "paytoUri" : "payto://iban/SANDBOXX/DE948559?receiver-name=admin" - } - -Note that ``jrluser`` is the same username / bank account name -as in the ``register`` example (see above). - -sandbox demobank new-ebicssubscriber -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank new-ebicssubscriber`` command associates a new Ebics -subscriber to an existing bank account. -It takes several options, all required: - -:: - - --host-id TEXT Ebics host ID - --partner-id TEXT Ebics partner ID - --user-id TEXT Ebics user ID - --bank-account TEXT Label of the bank account to associate - with this Ebics subscriber - -For example: - -.. code-block: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank new-ebicssubscriber \ - --host-id testhost \ - --partner-id partner01 \ - --user-id user02 \ - --bank-account jrluser - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example, and that ``partner01`` is the same as in the -``ebicssubscriber create`` example (see above). -The ``user02`` is new. -The ``--bank-account jrluser`` is the same as in the -``info`` example (see above). -You can see the effect of the ``new-ebicssubscriber`` command -with the ``sandbox ebicssubscriber list`` -and ``sandbox bankaccount list`` commands. - -sandbox demobank new-transaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank new-transaction`` command initiates a new transaction. -It takes several options, all required: - -:: - - --bank-account TEXT Label of the bank account to be - debited for the transaction - --payto-with-subject TEXT Payto address including the - subject as a query parameter - --amount CUR:X.Y Amount to transfer - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank new-transaction \ - --bank-account jrluser \ - --payto-with-subject 'payto://FIXME/?message=1kg+coffee' \ - --amount EUR:10.50 - FIXME: Any output? - -Note that ``--bank-account jrluser`` is the same as in the -``info`` and ``new-ebicssubscriber`` command examples (see above). - - -connections ------------ - -The ``connections`` set of commands handle connections between -the bank(s) and Nexus. -It has several subcommands: -new-ebics-connection, -list-connections, -show-connection, -delete-connection, -export-backup, -restore-backup, -get-key-letter, -connect, -list-offered-bank-accounts, -download-bank-accounts, -import-bank-account. - -Generally, you will create a connection, save its critical key information -to a safe location, then use the connection to find and import a bank -account, for further use. - -Several commands take a ``CONNECTION_NAME`` argument. -In the following examples, we use ``conn01`` for that. -Also, for demonstration purposes, we use the sandbox EBICS services, -so the ``EBICS_URL`` follows the previous examples in the ``sandbox`` -command, as the value of environment variable ``LIBEUFIN_SANDBOX_URL`` -suffixed with ``/ebicsweb``, i.e., ``http://localhost:5016/ebicsweb``. - -connections new-ebics-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections new-ebics-connection`` command creates a new connection -between an EBICS service and the Nexus. -It takes one arg, the ``CONNECTION_NAME``, and four required options: - -:: - - --ebics-url TEXT EBICS URL - --host-id TEXT Host ID - --partner-id TEXT Partner ID - --ebics-user-id TEXT Ebics user ID - -For example: - -.. code-block:: console - - $ libeufin-cli connections new-ebics-connection \ - --ebics-url http://localhost:5016/ebicsweb \ - --host-id testhost \ - --partner-id partner01 \ - --ebics-user-id user02 \ - conn01 - -Note that the ``testhost``, ``partner01``, and ``user02`` are the same as -in the ``sandbox demobank new-ebicssubscriber`` command (see above). - -connections list-connections -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections list-connections`` command lists connections in Nexus. -For example: - -.. code-block:: console - - $ libeufin-cli connections list-connections - { - "bankConnections" : [ { - "name" : "conn01", - "type" : "ebics" - } ] - } - -The name of the connection is ``conn01`` as in the -``connections new-ebics-connection`` example (see above). - -connections show-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections show-connection`` command displays information -about a specific connection. -It takes one argument, the ``CONNECTION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections show-connection conn01 - { - "type" : "ebics", - "owner" : "foo", - "ready" : true, - "details" : { - "ebicsUrl" : "http://localhost:5016/ebicsweb", - "ebicsHostId" : "testhost", - "partnerId" : "partner01", - "userId" : "user02" - } - } - -The details are the same as in the ``connections new-ebics-connections`` -example (see above). - -connections delete-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections delete-connection`` command deletes a bank connection. -It takes one argument, the ``CONNECTION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections delete-connection conn01 - -connections export-backup -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections export-backup`` command writes key and signature -information to a backup file (which you should take care to store -in a secure location). -It takes one argument, the ``CONNECTION_NAME`` and two required options: - -:: - - --passphrase TEXT Passphrase for locking the backup - --output-file TEXT Where to store the backup - -For example: - -.. code-block:: console - - $ libeufin-cli connections export-backup \ - --passphrase secret \ - --output-file sig-and-key-info \ - conn01 - FIXME: Output? - -See: https://bugs.gnunet.org/view.php?id=7180 - -connections restore-backup -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections get-key-letter -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections get-key-letter`` command creates a PDF file -that contains key information. -It takes two arguments, ``CONNECTION_NAME`` and ``OUTPUT_FILE``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections get-key-letter conn01 key-letter.pdf - -This creates file ``key-letter.pdf`` in the current working directory. - -connections connect -^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections list-offered-bank-accounts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections download-bank-accounts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections import-bank-account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - - -users ------ - -The ``libeufin-cli users`` command manages users authorized to -operate Nexus. -It has several subcommands: self, list, create, change-password. -The ``create`` and ``change-password`` commands can only be issued -by the superuser -(as configured by the ``libeufin-nexus superuser`` command), -while the ``self`` and ``list`` commands can be issued by any user. - -In the following ``users`` examples, we assume that previously -the command ``libeufin-nexus superuser foo`` was issued, and -that the current username and password are for that user -(via environment variables ``LIBEUFIN_NEXUS_USERNAME`` and -``LIBEUFIN_NEXUS_PASSWORD``, see above). - -users self -^^^^^^^^^^ - -The ``users self`` command displays information for the current user. - -For example: - -.. code-block:: console - - $ libeufin-cli users self - { - "username" : "foo", - "superuser" : true - } - -users list -^^^^^^^^^^ - -The ``users list`` command displays information for all the -users authorized to operate Nexus. - -For example: - -.. code-block:: console - - $ libeufin-cli users list - { - "users" : [ { - "username" : "foo", - "superuser" : true - } ] - } - -In this example, there is only one user, the superuser ``foo``. - -users create -^^^^^^^^^^^^ - -The ``users create`` command creates a normal (non-superuser) user. -It takes one argument, the ``USERNAME`` and one option, -``--password TEXT``. -If you omit the option, **libeufin-cli** will prompt you for the password. - -For example: - -.. code-block:: console - - $ libeufin-cli users create --password easy jrluser - { - "message" : "New user 'jrluser' registered" - } - $ libeufin-cli users list - { - "users" : [ { - "username" : "foo", - "superuser" : true - }, { - "username" : "jrluser", - "superuser" : false - } ] - } - -In this example, we create the same user as for the sandbox examples -(see above). -Note that the system now includes two users. - -users change-password -^^^^^^^^^^^^^^^^^^^^^ - -The ``users change-password`` command changes the password for a user. -It takes one argument, the ``USERNAME`` and one option, -``--new-password TEXT``. -If you omit the option, **libeufin-cli** will prompt you for the password. - -For example: - -.. code-block:: console - - $ libeufin-cli users change-password --new-password hard jrluser - { - "message" : "Password successfully changed" - } - - -permissions ------------ - -The ``libeufin-cli permissions`` command manages permissions -for operations on Nexus. -It has three subcommands: list, grant, revoke. -All three commands can only be issued by the superuser. - -permissions list -^^^^^^^^^^^^^^^^ - -The ``permissions list`` command lists the granted permissions. -At the beginning of a session, there are none: - -.. code-block:: console - - $ libeufin-cli permissions list - { - "permissions" : [ ] - } - - -permissions grant -^^^^^^^^^^^^^^^^^ - -The ``permissions grant`` command adds a permission to the list -of granted permissions. -It takes five arguments: ``SUBJECT_TYPE``, ``SUBJECT_ID``, -``RESOURCE_TYPE``, ``RESOURCE_ID``, ``PERMISSION_NAME``. - -FIXME: The subject type and id, resource type and id, are ... - -The ``PERMISSION_NAME`` is one of the following: - -- ``facade.talerwiregateway.history`` -- ``facade.talerwiregateway.transfer`` -- ``facade.anastasis.history`` - -For example: - -.. code-block:: console - - $ libeufin-cli permissions grant \ - some-subject-type some-subject-id \ - some-resource-type some-resource-id \ - facade.anastasis.history - { } - $ libeufin-cli permissions list - { - "permissions" : [ { - "subject_type" : "some-subject-type", - "subject_id" : "some-subject-id", - "resource_type" : "some-resource-type", - "resource_id" : "some-resource-id", - "permission_name" : "facade.anastasis.history" - } ] - } - -permissions revoke -^^^^^^^^^^^^^^^^^^ - -The ``permissions revoke`` command does the opposite of the -``permissions grant`` command. -It takes the same arguments as the ``permissions grant`` command: -``SUBJECT_TYPE``, ``SUBJECT_ID``, ``RESOURCE_TYPE``, ``RESOURCE_ID``, -``PERMISSION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli permissions revoke \ - some-subject-type some-subject-id \ - some-resource-type some-resource-id \ - facade.anastasis.history - { } - $ libeufin-cli permissions list - { - "permissions" : [ ] - } - -This example undoes the effect of the previous (``permissions grant``) example. - - -accounts --------- - -WRITEME - -accounts transactions -^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-status -^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-schedule -^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-delete -^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts submit-payments -^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts show-payment -^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts show -^^^^^^^^^^^^^ - -WRITEME - -accounts prepare-payment -^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts list-tasks -^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts list-payments -^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts fetch-transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts delete-payment -^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - - -facades -------- - -WRITEME - -facades new-taler-wire-gateway-facade -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -facades new-anastasis-facade -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -facades list -^^^^^^^^^^^^ - -WRITEME - - -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>. diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index a0ed99ff..5eb42cab 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -93,7 +93,7 @@ Its options are as follows: 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, enabled by default, causes the command to check the database and submit only once, and then return. + This flag causes the command to check the database and submit only once, and then return. ebics-fetch @@ -105,6 +105,8 @@ The files type can be given as an argument to select what will be fetched. If no * ``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. **-h** \| **--help** @@ -117,10 +119,26 @@ The files type can be given as an argument to select what will be fetched. If no 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, enabled by default, causes the command to perform one download and return. + 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. +serve +----- + +This command starts the HTTP server. + +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. +**--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. + initiate-payment ---------------- diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst index e70ff7b3..8aabe883 100644 --- a/manpages/libeufin-nexus.conf.5.rst +++ b/manpages/libeufin-nexus.conf.5.rst @@ -116,8 +116,8 @@ HOST_BASE_URL BANK_DIALECT Name of the following combination: EBICS version and ISO20022 recommendations - that Nexus would honor in the communication with the bank. Currently only the - 'postfinance' value is supported. + that Nexus would honor in the communication with the bank. Currently only the + ``postfinance`` or ``gls`` value is supported. HOST_ID EBICS specific: name of the EBICS host @@ -164,6 +164,63 @@ FREQUENCY Duration value to instruct the ``ebics-fetch`` subcommand how often it should download from the bank. +IGNORE_TRANSACTIONS_BEFORE + Ignore all transactions before a certain YYYY-MM-DD date, useful when you want to use an existing account with old transactions that should not be bounced. + +HTTP SERVER OPTIONS +------------------- + +The following configuration value(s) belong to the “[nexus-httpd]” section. + +SERVE + This can either be ``tcp`` or ``unix``. + +PORT + Port on which the HTTP server listens, e.g. 9967. + Only used if ``SERVE`` is ``tcp``. + +BIND_TO + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname. + Only used if ``SERVE`` is ``tcp``. + +UNIXPATH + Which unix domain path should we bind to? + Only used if ``SERVE`` is ``unix``. + +UNIXPATH_MODE + What should be the file access permissions for ``UNIXPATH``? + Only used if ``SERVE`` is ``unix``. + +HTTP WIRE GATEWAY API OPTIONS +----------------------------- + +The following configuration value(s) belong to the “[nexus-httpd-wire-gateway-api]” section. + +ENABLED + Whether to serve the Wire Gateway API. + +AUTH_METHOD + How to authenticate this API. This can either be ``none`` or ``bearer-token``. + +AUTH_BEARER_TOKEN + The expected token. + Only used if ``AUTH_METHOD`` is ``bearer-token``. + +HTTP REVENUE API OPTIONS +------------------------ + +The following configuration value(s) belong to the “[nexus-httpd-revenue-api]” section. + +ENABLED + Whether to serve the Revenue API. + +AUTH_METHOD + How to authenticate this API. This can either be ``none`` or ``bearer-token``. + +AUTH_BEARER_TOKEN + The expected token. + Only used if ``AUTH_METHOD`` is ``bearer-token``. + DATABASE OPTIONS ---------------- diff --git a/manpages/libeufin-sandbox.1.rst b/manpages/libeufin-sandbox.1.rst deleted file mode 100644 index 6f0948d0..00000000 --- a/manpages/libeufin-sandbox.1.rst +++ /dev/null @@ -1,227 +0,0 @@ -libeufin-sandbox(1) -################### - -.. only:: html - - Name - ==== - - **libeufin-sandbox** - Simulate a banking system core - with EBICS access to bank accounts - - -Synopsis -======== - -**libeufin-sandbox** -[**-h** | **--help**] -[**--version**] -COMMAND [ARGS...] - -Commands: serve, reset-tables, config, make-transaction, camt053tick -default-exchange - - -Description -=========== - -**libeufin-sandbox** is a program to simulate a banking system core -with EBICS access to bank accounts. -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-sandbox** accepts commands directly, -useful for configuring one or more "demobank" (simulated bank) instances. - -Its options are as follows: - -**-h** \| **--help** - Print short help on options. - -**–version** - Print version information. - -The interaction model is as follows: - -.. @MS Is the order of the first two steps correct? - Or are some of the commands to be used AFTER ‘serve’ starts? - Or is it a mix? (I believe it is a mix, but am not sure.) - -- Configure the sandbox with commands ``config``, ``default-exchange``, - ``make-transaction``, and ``camt053tick``. - -- Start the HTTP server with command ``serve``. - Let this run in a shell, writing logs to stderr. - -- Point program **libeufin-nexus** at the sandbox. - -- 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. - - -config ------- - -This command takes argument ``NAME`` and creates a demobank with that name. - -Option ``--currency CUR`` (default: ``EUR``) specifies another currency. -Option ``--captcha-url $URL`` specifies where the wallet user is going -to be redirected to confirm the withdrawal operation. This $URL should -point to the bank frontend. More precisely to the UI that let the user -finish a withdrawal operation that needs to be confirmed. Example of -this value may be "https://bank.domain/#/operation/{wopid}" where -"https://bank.domain" returns the demobank SPA and the demobank view under -the route "/operation/{wopid}" will show the status of the operation id {wopid}. -Note that "{wopid}" is literally in the --captcha-url config and replaced at -runtime by the sandbox server. -Option ``--bank-debt-limit N`` (default: 1000000) specifies that -the bank debt limit should be N (units of currency). -Similarly, option ``--users-debt-limit N`` (default: 1000) specifies -that the users debt limit should be N (units of currency). - -For example: - -.. code-block:: console - - $ libeufin-sandbox config default - -This creates the demobank ``default`` with currency ``EUR``, -bank debt limit 1000000, users debt limit 1000, -and allows registrations. - - -default-exchange ----------------- - -This command sets the exchange that a demobank will suggest to wallets. -(Wallets are of course free to disregard the suggestion and choose -another exchange.) -It requires two arguments, ``EXCHANGE-BASEURL`` and ``EXCHANGE-PAYTO``. -The option ``--demobank NAME`` (default: ``default``) specifies -which demobank this setting affects. - -For example: - -.. code-block:: console - - $ libeufin-sandbox default-exchange \ - --demobank bank01 \ - https://exchange.example.com/ \ - payto://iban/CH9300762011623852957 - -This sets the default exchange for demobank ``bank01``. -It is an error if the demobank does not exist. - - -make-transaction ----------------- - -This is a "legacy" command, useful in a previous iteration of LibEuFin -and for internal testing. -It creates and records a wire transfer transaction in the database. - -It takes two arguments and several required options. -The arguments are ``AMOUNT``, in ``CUR:X.Y`` format; -and ``SUBJECT``, a short textual description of the transaction. -The options are: ``--credit-account LABEL`` and ``--debit-account LABEL``, -where each LABEL names a bank account for receiving and issuing, -respectively, the wire transfer. -The option ``--demobank NAME`` (default: ``default``) specifies -in which demobank the wire transfer occurs. - -.. note:: - - If you have not yet called ``config``, this command creates - a demobank named ``default`` on its first use. The currency, - and bank debt limit have the same defaults as for the ``config`` - command. The users debt limit, however, defaults to 10000. - -FIXME: How to achieve the same result with **libeufin-cli**? - - -camt053tick ------------ - -This command advances the internal time step that the demobank -uses to group transactions for reporting. -(Successive transactions will be inserted in a new Camt.053 report.) - -For example: - -.. code-block:: console - - $ libeufin-sandbox camt053tick - -FIXME: How to achieve the same result with **libeufin-cli**? - - -serve ------ - -This command starts the HTTP server, listening on port 5000. -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. - -.. note:: - - If you have not yet called ``config``, this command creates - a demobank named ``default`` on its first use. The currency, - and bank debt limit have the same defaults as for the ``config`` - command. The users debt limit, however, defaults to 10000. - -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 variables need to be set: - -``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` - The password required for later use by **libeufin-cli**. - For testing purposes, you can use option ``--no-auth`` to disable - this requirement. - (In that case, this environment variable need not be set.) - -``LIBEUFIN_SANDBOX_DB_CONNECTION`` - This specifies the database **libeufin-sandbox** uses to maintain state. - Currently, both Sqlite and PostgreSQL are supported. - (Only one needs to be specified.) - Examples: - - - ``jdbc:sqlite:/tmp/libeufin-sandbox.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-sandbox** creates them -again, automatically.) - -It should only be used when the sandbox is quiescent. - - -See Also -======== - -.. TODO: libeufin-nexus(1), libeufin-cli(1). - - -Bugs -==== - -Report bugs by using https://bugs.taler.net or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 3074f68b..ee5d3cd1 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -254,19 +254,29 @@ PRIVACY_ETAG EXCHANGE KYC PROVIDER OPTIONS ----------------------------- -The following options must be in the section "[kyc-provider-XXX]" sections. - -COST - Relative cost of the KYC provider, non-negative number. +The following options must be in the section "[kyc-provider-$PROVIDER_NAME]" sections. LOGIC API type of the KYC provider. -USER_TYPE - Type of user this provider is for, either INDIVIDUAL or BUSINESS. +CONVERTER + Name of a program to run on the output of the plugin + to convert the result into the desired set of attributes. + The converter must create a log for the system administrator + if the provided inputs do not match expectations. + Note that the converter will be expected to output the + set of attributes listed under the respective ``[kyc-check-*]`` + sections. Calling the converter with ``--list-outputs`` + should generate a (newline-separated) list of attributes + the converter promises to generate in its JSON output + (when run regularly). + +COST + Optional cost, useful if clients want to voluntarily + trigger authentication procedures for attestation. -PROVIDED_CHECKS - List of checks performed by this provider. Space-separated names of checks, must match check names in legitimization rules. +Additional logic-specific options may be given in the +section. EXCHANGE KYC OAUTH2 OPTIONS @@ -362,6 +372,169 @@ WEBHOOK_AUTH_TOKEN Authentication token Persona must supply to our webhook. This is an optional setting. +EXCHANGE KYC CHECK OPTIONS +-------------------------- + +The following options must be in "[kyc-check-$CHECK_NAME]" sections. + +TYPE + Which type of check is this? Also determines + the SPA form to show to the user for this check. + + * INFO: wait for staff or contact staff out-of band + (only information shown, no SPA action) + * FORM: SPA should show an inline (HTML) form + * LINK: SPA may start external KYC process or upload + +VOLUNTARY + Optional. Set to YES to allow this check be + done voluntarily by a client (they may then + still have to pay for it). Used to offer the + SPA to display checks even if they are + not required. Default is NO. + +PROVIDER_ID + Provider id, present only if type is LINK. + Refers to a ``kyc-provider-$PROVIDER_ID`` section. + +FORM_NAME + Name of the SPA form, if type is FORM + "INFO" and "LINK" are reserved and must not be used. + The exchange server and the SPA must agree on a list + of supported forms and the resulting attributes. + The SPA should include a JSON resource file + "forms.json" mapping form names to arrays of + attribute names each form provides. + The list of possible FORM names is fixed in the SPA + for a particular exchange release. + +DESCRIPTION + Descriptions to use in the SPA to display the check. + +DESCRIPTION_I18N + JSON with internationalized descriptions to use + in the SPA to display the check. + +REQUIRES + ';'-separated list of fields that the CONTEXT must + provide as inputs to this check. For example, + for a FORM of type CHOICE, this might state + ``choices: string[];``. The type after the ":" + is for now purely for documentation and is + not checked. However, it may be shown to AML staff + when they configure measures. + +OUTPUTS = business_name street city country registration + Description of the outputs provided by the check. + Basically, the check's output is expected to + provide the following fields as attribute inputs into + a subsequent AML program. + Only given for type FORM; INFO never has any outputs, + and for type LINK we can obtain the same information + from the CONVERTER via ``--list-outputs``. + +FALLBACK + Name of an **original** measure to take if the check fails + (for any reason, e.g. provider or form fail to + satisfy constraints or provider signals user error) + Usually should point to a measure that requests + AML staff to investigate. The fallback measure + context always includes the reasons for the + failure. + +EXCHANGE KYC RULES +------------------ + +The following options must be in "[kyc-rule-$RULE_NAME]" sections. + +OPERATION_TYPE = WITHDRAW + Operation that triggers this rule. + Must be one of WITHDRAW, DEPOSIT, P2P-RECEIVE + or WALLET-BALANCE. + +NEXT_MEASURES + Space-separated list of next measures to be performed. + The SPA should display *all* of these measures to the user. + (They have a choice of either which ones, or in + which order they are to be performed.) + A special measure name "verboten" is used if the + specified threshold may never be crossed + (under this set of rules). + +IS_AND_COMBINATOR + "YES" if all NEXT_MEASURES will eventually need + to be satisfied, "NO" the user has a choice between + them. Not actually enforced by the exchange, but + primarily used to inform the user whether this is + an "and" or "or". YES for "and". + +EXPOSED + YES if the rule (specifically, operation type, + threshold, timeframe) and the general nature of + the next measure (verboten or approval required) + should be exposed to the client. + Defaults to NO if not set. + +THRESHOLD + Threshold amount above which the rule is + triggered. The total must be exceeded in the given + timeframe. + +TIMEFRAME + Timeframe over which the amount to be compared to + the THRESHOLD is calculated (for example, "30 days"). + Ignored for WALLET-BALANCE. Can be 'forever'. + +ENABLED = NO + Set to YES to enable the rule (default is NO). + + +EXCHANGE AML PROGRAMS +--------------------- + +The following options must be in "[aml-program-$PROG_NAME]" sections. + +COMMAND + Name of the program to run. Must match a binary + on the local machine where the exchange is running. + +DESCRIPTION + Human-readable description of what this + AML helper program will do. Used to show + to the AML staff. + +ENABLED + True if this AML program is enabled (and thus can be + used in measures and exposed to AML staff). + Optional, default is NO. + +FALLBACK + Name of an **original** measure to take if COMMAND fails + Usually points to a measure that asks AML staff + to contact the systems administrator. The fallback measure + context always includes the reasons for the + failure. + +EXCHANGE KYC MEASURES +--------------------- + +The following options must be in "[kyc-measure-$MEASURE_NAME]" sections. These sections define the **original** measures. + +CHECK_NAME + Name of a possible check for this measure. Optional. + If not given, PROGRAM should be run immediately + (on an empty set of attributes). + +CONTEXT = {"choices":["individual","business"]} + Context for the check. The context can be + just an empty JSON object if there is none. + +PROGRAM + Program to run on the context and check data to + determine the outcome and next measure. + Refers to a ``[aml-program-$PROG_NAME]`` section name. + + EXCHANGE EXTENSIONS OPTIONS --------------------------- |