path: root/man/libeufin-sandbox.1

.\" Man page generated from reStructuredText.
.
.TH "LIBEUFIN-SANDBOX" "1" "Jul 06, 2022" "0.9" "GNU Taler"
.SH NAME
libeufin-sandbox \- simulate core banking system with EBICS access to bank accounts
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBlibeufin\-sandbox\fP
[\fB\-h\fP\ |\ \fB\-\-help\fP]
[\fB\-\-version\fP]
COMMAND [ARGS...]
.sp
Commands: serve, reset\-tables, config, make\-transaction, camt053tick
default\-exchange
.SH DESCRIPTION
.sp
\fBlibeufin\-sandbox\fP 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 \fBlibeufin\-cli\fP is the preferred front end
for that mode of operation.
There is also a mode where \fBlibeufin\-sandbox\fP accepts commands directly,
useful for configuring one or more "demobank" (simulated bank) instances.
.sp
Its options are as follows:
.INDENT 0.0
.TP
\fB\-h\fP | \fB\-\-help\fP
Print short help on options.
.TP
\fB–version\fP
Print version information.
.UNINDENT
.sp
The interaction model is as follows:
.INDENT 0.0
.IP \(bu 2
Configure the sandbox with commands \fBconfig\fP, \fBdefault\-exchange\fP,
\fBmake\-transaction\fP, and \fBcamt053tick\fP\&.
.IP \(bu 2
Start the HTTP server with command \fBserve\fP\&.
Let this run in a shell, writing logs to stderr.
.IP \(bu 2
Point program \fBlibeufin\-nexus\fP at the sandbox.
.IP \(bu 2
Interact with \fBlibeufin\-nexus\fP\&.
.IP \(bu 2
When finished, interrupt the \fBserve\fP process and clean up with command
\fBreset\-tables\fP\&.
.UNINDENT
.sp
The following sections describe each command in detail.
.SS config
.sp
This command takes argument \fBNAME\fP and creates a demobank with that name.
.sp
Option \fB\-\-currency CUR\fP (default: \fBEUR\fP) specifes another currency.
Option \fB\-\-bank\-debt\-limit N\fP (default: 1000000) specifies that
the bank debt limit should be N (units of currency).
Similarly, option \fB\-\-users\-debt\-limit N\fP (default: 1000) specifies
that the users debt limit should be N (units of currency).
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ libeufin\-sandbox config default
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This creates the demobank \fBdefault\fP with currency \fBEUR\fP,
bank debt limit 1000000, users debt limit 1000,
and allows registrations.
.SS default\-exchange
.sp
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, \fBEXCHANGE\-BASEURL\fP and \fBEXCHANGE\-PAYTO\fP\&.
The option \fB\-\-demobank NAME\fP (default: \fBdefault\fP) specifies
which demobank this setting affects.
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ libeufin\-sandbox default\-exchange \e
    \-\-demobank bank01 \e
    https://exchange.example.com/ \e
    payto://iban/CH9300762011623852957
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This sets the default exchange for demobank \fBbank01\fP\&.
It is an error if the demobank does not exist.
.SS make\-transaction
.sp
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.
.sp
It takes two arguments and several required options.
The arguments are \fBAMOUNT\fP, in \fBCUR:X.Y\fP format;
and \fBSUBJECT\fP, a short textual description of the transaction.
The options are: \fB\-\-credit\-account LABEL\fP and \fB\-\-debit\-account LABEL\fP,
where each LABEL names a bank account for receiving and issuing,
respectively, the wire transfer.
The option \fB\-\-demobank NAME\fP (default: \fBdefault\fP) specifies
in which demobank the wire transfer occurs.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you have not yet called \fBconfig\fP, this command creates
a demobank named \fBdefault\fP on its first use.  The currency,
and bank debt limit have the same defaults as for the \fBconfig\fP
command.  The users debt limit, however, defaults to 10000.
.UNINDENT
.UNINDENT
.sp
FIXME: How to achieve the same result with \fBlibeufin\-cli\fP?
.SS camt053tick
.sp
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.)
.sp
For example:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ libeufin\-sandbox camt053tick
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
FIXME: How to achieve the same result with \fBlibeufin\-cli\fP?
.SS serve
.sp
This command starts the HTTP server, listening on port 5000.
To use a different port, use option \fB\-\-port INT\fP\&.
To listen, instead, on a Unix domain socket,
use option \fB\-\-with\-unix\-socket PATH\fP\&.
When both \fB\-\-port\fP and \fB\-\-with\-unix\-socket\fP are given,
\fB\-\-with\-unix\-socket\fP takes precedence.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If you have not yet called \fBconfig\fP, this command creates
a demobank named \fBdefault\fP on its first use.  The currency,
and bank debt limit have the same defaults as for the \fBconfig\fP
command.  The users debt limit, however, defaults to 10000.
.UNINDENT
.UNINDENT
.sp
The process runs in the foreground, writing its logs to standard error.
The normal log level is \fBDEBUG\fP\&.
To change it, use \fB\-\-log\-level LEVEL\fP, where \fBLEVEL\fP is one of:
\fBERROR\fP, \fBWARN\fP, \fBINFO\fP, \fBDEBUG\fP, \fBTRACE\fP\&.
.sp
Before invoking \fBserve\fP, the following environment variables need to be set:
.INDENT 0.0
.TP
.B \fBLIBEUFIN_SANDBOX_ADMIN_PASSWORD\fP
The password required for later use by \fBlibeufin\-cli\fP\&.
For testing purposes, you can use option \fB\-\-no\-auth\fP to disable
this requirement.
(In that case, this environment variable need not be set.)
.TP
.B \fBLIBEUFIN_SANDBOX_DB_CONNECTION\fP
This specifies the database \fBlibeufin\-sandbox\fP uses to maintain state.
Currently, both Sqlite and PostgreSQL are supported.
(Only one needs to be specified.)
Examples:
.INDENT 7.0
.IP \(bu 2
\fBjdbc:sqlite:/tmp/libeufin\-sandbox.db\fP
.IP \(bu 2
\fBjdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret\fP
.UNINDENT
.UNINDENT
.sp
Normally, the \fBserve\fP command runs until interrupted.
When run in a shell, you can use \fBControl\-C\fP for that.
.SS reset\-tables
.sp
This command drops all the tables in the internal database.
(The next time the tables are needed, \fBlibeufin\-sandbox\fP creates them
again, automatically.)
.sp
It should only be used when the sandbox is quiescent.
.SH SEE ALSO
.SH BUGS
.sp
Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic
mail to <\fI\%taler@gnu.org\fP>.
.SH AUTHOR
GNU Taler contributors
.SH COPYRIGHT
2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
.\" Generated by docutils manpage writer.
.