diff options
Diffstat (limited to 'man/taler.conf.5')
| -rw-r--r-- | man/taler.conf.5 | 174 |
1 files changed, 117 insertions, 57 deletions
diff --git a/man/taler.conf.5 b/man/taler.conf.5 index 4467ef44..85e2fb27 100644 --- a/man/taler.conf.5 +++ b/man/taler.conf.5 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER.CONF" "5" "Apr 16, 2023" "0.9" "GNU Taler" -.SH NAME -taler.conf \- Taler configuration file . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER.CONF" "5" "May 18, 2023" "0.9" "GNU Taler" +.SH NAME +taler.conf \- Taler configuration file .SH DESCRIPTION .sp The configuration file is line\-oriented. @@ -65,6 +65,46 @@ Values that represent an amount are in the usual amount syntax: \fBCURRENCY:VALUE.FRACTION\fP, e.g. \fBEUR:1.50\fP\&. The \fBFRACTION\fP portion may extend up to 8 places. .sp +The “[PATHS]” section is special in that it contains paths that can be +referenced using “$” in other configuration values that specify +\fIfilenames\fP\&. Note that configuration options that are not specifically +retrieved by the application as \fIfilenames\fP will not see “$”\-expressions +expanded. To expand “$”\-expressions when using \fBtaler\-config\fP, you must pass +the \fB\-f\fP command\-line option. +.sp +The system automatically pre\-populates the “[PATHS]” section with a few values +at run\-time in addition to the values that are in the actual configuration +file. These automatically generated values refer to installation properties +from \fI\%GNU autoconf\fP\&. The +values are usually dependent on an \fBINSTALL_PREFIX\fP which is determined by +the \fB\-\-prefix\fP option given to configure. The canonical values are: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ +.IP \(bu 2 +DOCDIR = $INSTALL_PREFIX/share/doc/taler/ +.IP \(bu 2 +ICONDIR = $INSTALL_PREFIX/share/icons/ +.IP \(bu 2 +LOCALEDIR = $INSTALL_PREFIX/share/locale/ +.IP \(bu 2 +PREFIX = $INSTALL_PREFIX/ +.IP \(bu 2 +BINDIR = $INSTALL_PREFIX/bin/ +.IP \(bu 2 +LIBDIR = $INSTALL_PREFIX/lib/taler/ +.IP \(bu 2 +DATADIR = $INSTALL_PREFIX/share/taler/ +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that on some platforms, the given paths may differ depending +on how the system was compiled or installed, the above are just the +canonical locations of the various resources. +.sp Files containing default values for many of the options described below are installed under \fB$TALER_PREFIX/share/taler/config.d/\fP\&. The configuration file given with \fB\-c\fP to Taler binaries @@ -89,10 +129,6 @@ Name of the currency, e.g.\ “EUR” for Euro. .B CURRENCY_ROUND_UNIT Smallest amount in this currency that can be transferred using the underlying RTGS. For example: "EUR:0.01" or "JPY:1". -.TP -.B AML_THRESHOLD -Largest amount in this currency that can be transferred per month without -an AML staff member doing a (manual) AML check. For example: "USD:1000000". .UNINDENT .sp The “[PATHS]” section is special in that it contains paths that can be @@ -140,6 +176,20 @@ exchange\(aqs long\-time offline signing key. Location of the master private key on disk. Only used by tools that can be run offline (as the master key is for offline signing). .TP +.B AML_THRESHOLD +Largest amount in this currency that can be transferred per month without +an AML staff member doing a (manual) AML check. For example: "USD:1000000". +.TP +.B KYC_AML_TRIGGER +Program to run on KYC attribute data to decide whether we should immediately flag an account for AML review. Program must return 0 if a manual AML review is not needed, and non\-zero to trigger an AML review. The KYC attribute data of the new user will be passed on standard\-input. +.TP +.B ENABLE_TIPPING +This option can be used to announce that an exchange does not allow +the use of the reserves for tipping. The default is YES which means +that tipping is allowed. The option merely announces that +tipping is enabled or disabled, and protocol\-compliant merchant +backends will then enable or disable the feature accordingly. +.TP .B BASE_URL The base URL under which the exchange can be reached. Added to wire transfers to enable tracking by merchants. @@ -239,14 +289,14 @@ The following options must be in the section "[kyc\-provider\-XXX]" sections wit .B KYC_OAUTH2_VALIDITY Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". .TP -.B KYC_OAUTH2_AUTH_URL -URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "\fI\%http://localhost:8888/oauth/v2/auth\fP" (or "/token") +.B KYC_OAUTH2_AUTHORIZE_URL +URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: "\fI\%http://localhost:8888/oauth/v2/authorize\fP". To use the plugin in combination with the Challenger service\(aqs \fB/setup\fP step, append "#setup", thus "\fI\%https://challenger.example.com/authorize#setup\fP". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the \fB/setup\fP handler. .TP -.B KYC_OAUTH2_LOGIN_URL -URL of the OAuth2 endpoint to be used for KYC checks. The login URL will be encoded as part of the \(aqredirect_uri\(aq argument of the request to the KYC_AUTH2_AUTH_URL. Typically, the user will then be redirected to this URL to log in. Example: "\fI\%http://localhost:8888/oauth/v2/login\fP" +.B KYC_OAUTH2_TOKEN_URL +URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "\fI\%http://localhost:8888/oauth/v2/token\fP" (or just "/token") .TP .B KYC_OAUTH2_INFO_URL -URL of the endpoint where the OAuth 2.0 token can be used to download the user\(aqs details. The server will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "\fI\%http://localhost:8888/api/user/me\fP" or "\fI\%http://localhost:8888/oauth/v2/info\fP" +URL of the OAuth2\-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "\fI\%http://localhost:8888/api/user/me\fP" or "\fI\%http://localhost:8888/oauth/v2/info\fP" .TP .B KYC_OAUTH2_CLIENT_ID Client ID of the exchange when it talks to the KYC OAuth2 endpoint. @@ -291,6 +341,9 @@ Salt value to use for request idempotency. Optional, generated at random per pro .B KYC_PERSONA_SUBDOMAIN Subdomain to use under Persona. .TP +.B KYC_PERSONA_CONVERTER_HELPER +Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to "taler\-exchange\-kyc\-persona\-converter.sh". +.TP .B KYC_PERSONA_POST_URL URL to which the exchange will redirect the client\(aqs browser after successful authorization/login for the KYC process. .TP @@ -305,6 +358,53 @@ The following option must be in the section "[kyclogic\-persona]". .B WEBHOOK_AUTH_TOKEN Authentication token Persona must supply to our webhook. This is an optional setting. .UNINDENT +.SS EXCHANGE EXTENSIONS OPTIONS +.sp +The functionality of the exchange can be extended by extensions. Those are +shared libraries which implement the extension\-API of the exchange and are +located under \fB$LIBDIR\fP, starting with prefix \fBlibtaler_extension_\fP\&. Each +extension can be enabled by adding a dedicated section +"[exchange\-extension\-<extensionname>]" and the following option: +.INDENT 0.0 +.TP +.B ENABLED +If set to \fBYES\fP the extension \fB<extensionsname>\fP is enabled. Extension\-specific +options might be set in the same section. +.UNINDENT +.SS EXCHANGE EXTENSION FOR AGE RESTRICTION +.sp +The extension for age restriction support can be enabled by adding a section +"[exchange\-extension\-age_restriction]" with the following options: +.INDENT 0.0 +.TP +.B ENABLE +Must be set to \fBYES\fP in order to activate the extension. +.TP +.B AGE_GROUPS +A colon\-seperated string of increasing non\-negative integers, defining the +buckets of age groups supported by the exchange. Each integer marks the +beginning of the next age group. The zero\(aqth age group implicitely starts +with 0. For example, the string "10:18" would define three age groups: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Group 0: ages 0 through 9 (including) +.IP 2. 3 +Group 1: ages 10 through 17 (including) +.IP 3. 3 +Group 2: ages 18 and above +.UNINDENT +.UNINDENT +.UNINDENT +.sp +If not provided, the default value is "8:10:12:14:16:18:21". +.UNINDENT +.sp +\fBNote\fP: Age restriction is bound to specific denominations and must be +enabled for each selected denomination in the corresponding section by adding +the option \fBAGE_RESTRICTED = YES\fP, see \fI\%EXCHANGE COIN OPTIONS\fP\&. However, the +age groups are defined globally for all denominations. .SS EXCHANGE OFFLINE SIGNING OPTIONS .sp The following options must be in the section "[exchange\-offline]". @@ -536,6 +636,11 @@ denomination. .TP .B RSA_KEYSIZE What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA". +.TP +.B AGE_RESTRICTED +Setting this option to \fBYES\fP marks the denomination as age restricted +(default is \fBNO\fP). For this option to be accepted the extension for age +restriction MUST be enabled (see \fI\%EXCHANGE EXTENSION FOR AGE RESTRICTION\fP). .UNINDENT .SS MERCHANT OPTIONS .sp @@ -595,51 +700,6 @@ Name of the currency for which this exchange is used, e.g.\ “KUDOS”. The entire section is ignored if the currency does not match the currency we use, which must be given in the \fB[taler]\fP section. .UNINDENT -.SS KNOWN AUDITORS (for merchants) -.sp -The merchant configuration can include a list of known exchanges if the -merchant wants to specify that certain auditors are explicitly trusted. -For each trusted exchange, a section “[merchant\-auditor\-$NAME]” must exist, where -\fB$NAME\fP is a merchant\-given name for the auditor. The following options -must be given in each “[merchant\-auditor\-$NAME]” section. -.INDENT 0.0 -.TP -.B AUDITOR_BASE_URL -Base URL of the auditor, e.g.\ “\fI\%https://auditor.demo.taler.net/\fP” -.TP -.B AUDITOR_KEY -Crockford Base32 encoded auditor public key. -.TP -.B CURRENCY -Name of the currency for which this auditor is trusted, e.g.\ “KUDOS” -The entire section is ignored if the currency does not match the currency -we use, which must be given in the \fB[taler]\fP section. -.UNINDENT -.SS MERCHANT WIREWATCH OPTIONS -.sp -The name of the configuration section used by taler\-merchant\-wirewatch -can be changed via the command\-line. By default, it is simply -"[taler\-merchant\-wirewatch]". The options are: -.INDENT 0.0 -.TP -.B INSTANCE -Which instance of the backend should transactions be imported for by this wirewatcher. -.TP -.B WIRE_GATEWAY_URL -Under which URL is the wire gateway (libeufin facade) reachable that makes bank transfer data availalbe to us. -.TP -.B WIRE_GATEWAY_AUTH_METHOD -Which authentication method should be used (currently only "NONE" or "BASIC" are supported). -.TP -.B USERNAME -Username to give to the wire gateway when using "BASIC" authentication. -.TP -.B PASSWORD -Password to give to the wire gateway when using "BASIC" authentication. -.UNINDENT -.sp -Note that the libeufin facade type to configure for a taler\-merchant\-wirewatch -operation is the "Anastasis" facade. .SS AUDITOR OPTIONS .sp The following options must be in section “[auditor]” for the Taler |