-update man pages

1 files changed, 243 insertions, 0 deletions

diff --git a/man/libeufin-sandbox.1 b/man/libeufin-sandbox.1
new file mode 100644
index 00000000..d539c11f
--- /dev/null
+++ b/man/libeufin-sandbox.1
@@ -0,0 +1,243 @@
+.\" Man page generated from reStructuredText.
+.
+.TH "LIBEUFIN-SANDBOX" "1" "Jun 20, 2022" "0.8" "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-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+)
+.\" Generated by docutils manpage writer.
+.