commit 2fb93923da6f118b3f9edcb9f9df9710e9e38373
parent 37cf719982f1f4fb377ad956cde45f38df26fde7
Author: Christian Grothoff <christian@grothoff.org>
Date: Wed, 18 Nov 2026 13:57:47 +0100
keep documentation up-to-date with new environment variables
Diffstat:
6 files changed, 82 insertions(+), 49 deletions(-)
diff --git a/manpages/challenger-send-post.1.rst b/manpages/challenger-send-post.1.rst
@@ -94,6 +94,24 @@ from the environment of the invoking daemon, never from a configuration file.
printed as one space. A subject may wrap onto a second line; one that needs
a third fails the letter with status 50.
+**POSTAL_OPENING**
+ Salutation above the message. Optional; if it is unset or empty, it is
+ ``To whom it may concern,``.
+
+**POSTAL_CLOSING**
+ Closing below the message. Optional; if it is unset or empty, it is ``Best
+ regards``.
+
+**POSTAL_SIGNATURE**
+ Line under the closing, such as the sender's name and address. Optional; if
+ it is unset or empty, it is ``Taler Operations AG, c/o Berner
+ Fachhochschule, Höheweg 80, 2502 Biel/Bienne``. A deployment operated by
+ anyone else should set it.
+
+Opening, closing and signature are printed with runs of whitespace as one
+space, on one line each; one that does not fit on a line fails the letter with
+status 50. The date above the subject is always in English.
+
typst(1) must be installed and must support the ``--no-pdf-tags`` option.
@@ -132,8 +150,9 @@ delivery.
**50**
The transmission failed for a reason that could not be classified, including
- a message too long to be rendered on a single page and a **POSTAL_SUBJECT**
- too long for two lines.
+ a message too long to be rendered on a single page, a **POSTAL_SUBJECT**
+ too long for two lines, and a **POSTAL_OPENING**, **POSTAL_CLOSING** or
+ **POSTAL_SIGNATURE** too long for one.
See Also
diff --git a/manpages/challenger-send-sms-aspsms.1.rst b/manpages/challenger-send-sms-aspsms.1.rst
@@ -54,9 +54,16 @@ Environment
**ASPSMS_PASSWORD**
ASPSMS API password. Required.
-The helper fails with status 40 if either is unset or empty. Credentials are
-taken from the environment of the invoking daemon, never from a configuration
-file.
+**ASPSMS_SENDER**
+ Sender identity to show on the message (ASPSMS's ``Originator``), at most 11
+ alphanumeric or 16 numeric characters. Optional; if it is unset or empty,
+ the sender is ``Challenger``. An alphanumeric sender must be pre-registered
+ with the operator in several countries; where that applies, configure a
+ sender the operator accepts, or a numeric one.
+
+The helper fails with status 40 if either of the two required variables is
+unset or empty. Credentials are taken from the environment of the invoking
+daemon, never from a configuration file.
Exit Status
diff --git a/manpages/challenger-send-sms-budgetsms.1.rst b/manpages/challenger-send-sms-budgetsms.1.rst
@@ -49,9 +49,8 @@ rather than guessed at as a bad number, which also lets the dispatcher try the
next provider. The statuses that mean the outcome is unknown are only reachable
24 to 72 hours after sending and thus never within the polling window.
-This API requires a sender identity on every message, so unlike the other
-helpers this one sends a default sender that can be overridden; see
-**BUDGETSMS_SENDER** below.
+This API requires a sender identity on every message, so this helper always
+sends one, ``Challenger`` unless **BUDGETSMS_SENDER** below says otherwise.
Environment
diff --git a/manpages/challenger-send-sms-seven.1.rst b/manpages/challenger-send-sms-seven.1.rst
@@ -67,13 +67,17 @@ Environment
unset or empty, or if it contains a line break, as the key is sent in an
HTTP header.
+**SEVEN_SENDER**
+ Sender identity to show on the message, at most 11 alphanumeric or 16
+ numeric characters. Optional; if it is unset or empty, the sender is
+ ``Taler Ops``. An alphanumeric sender must be pre-registered with the
+ operator in several countries, and a sender the operator does not accept
+ fails every message; where that applies, configure a sender the operator
+ accepts, or a numeric one.
+
Credentials are taken from the environment of the invoking daemon, never from a
configuration file.
-No sender identity is configured by this helper: the account default applies.
-An alphanumeric sender must be pre-registered with the operator in several
-countries, and a sender the operator does not accept fails every message.
-
Exit Status
===========
diff --git a/manpages/challenger-send-sms.1.rst b/manpages/challenger-send-sms.1.rst
@@ -51,21 +51,22 @@ passed on and will be reported by whichever provider first classifies it.
Providers are resolved by name from the directory holding
**challenger-send-sms** itself, as ``challenger-send-sms-``\ *PROVIDER*, and are
-tried in the order ``telesign``, ``clicksend``, ``aspsms``. A provider whose
-helper is absent or not executable is skipped silently.
-
-Three further provider helpers are installed but not in that list:
-``seven`` (challenger-send-sms-seven(1)), ``gatewayapi``
-(challenger-send-sms-gatewayapi(1)) and ``budgetsms``
-(challenger-send-sms-budgetsms(1)). All three are operated inside the European
-Economic Area, which avoids the transfer of a phone number and a TAN to a third
-country that the other three providers involve. They have been written against
-the published specifications of their APIs and are covered by the offline test
-suite, but have not been exercised against a live account, which is why they
-are not enabled by default. To use one, add its name to the ``PROVIDERS``
-variable near the top of the **challenger-send-sms** script, in the order in
-which it should be tried; the credentials listed in each helper's manual page
-must be present in the environment of the invoking daemon.
+tried in the order ``gatewayapi``, ``budgetsms``, ``aspsms``, ``seven``,
+``telesign``, ``clicksend``. A provider whose helper is absent or not executable
+is skipped silently, and so, in effect, is one whose credentials are missing:
+it fails with status 40, and the next provider is tried. The credentials are
+listed in each helper's manual page and must be present in the environment of
+the invoking daemon.
+
+``gatewayapi`` (challenger-send-sms-gatewayapi(1)), ``budgetsms``
+(challenger-send-sms-budgetsms(1)) and ``seven`` (challenger-send-sms-seven(1))
+are operated inside the European Economic Area, which avoids transferring the
+phone number and the TAN to a third country; ``aspsms``
+(challenger-send-sms-aspsms(1)) is operated in Switzerland, ``telesign``
+(challenger-send-sms-telesign(1)) in the United States and ``clicksend``
+(challenger-send-sms-clicksend(1)) in Australia. The order is the ``PROVIDERS``
+variable near the top of the **challenger-send-sms** script; edit it to change
+the order or to leave a provider out.
Whether a failing provider causes the next one to be tried depends on the class
of the failure. An address that one provider rejects will be rejected by all of
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
@@ -248,7 +248,7 @@ configuration contains two configuration options.
[challenger]
ADDRESS_TYPE = email
- AUTH_COMMAND = challenger-send-email.sh
+ AUTH_COMMAND = challenger-send-email
# ... rest of file ...
Challenger comes with ``AUTH_COMMAND`` shell scripts for sending e-mail, SMS
@@ -262,11 +262,14 @@ configuration file, so they are configured by setting those variables for the
*SMS transmission providers* below. In any case, these scripts should be
primarily seen as *examples* on how to write authentication commands.
-Two variables that are not credentials set what the e-mail and postal scripts
-call their message, and both are optional: ``EMAIL_SUBJECT`` is the subject of
-the mail that ``challenger-send-email`` sends (``KYC Challenger`` by default),
-and ``POSTAL_SUBJECT`` the subject line of the letter that
-``challenger-send-post`` posts (``Address validation`` by default). See
+Further variables, all optional and none of them credentials, set the texts
+around the message. ``EMAIL_SUBJECT`` is the subject of the mail that
+``challenger-send-email`` sends (``KYC Challenger`` by default).
+``POSTAL_SUBJECT``, ``POSTAL_OPENING``, ``POSTAL_CLOSING`` and
+``POSTAL_SIGNATURE`` are the subject line, salutation, closing and signature
+line of the letter that ``challenger-send-post`` posts; their defaults are
+English, and the default signature is that of Taler Operations AG, so any other
+operator should set at least ``POSTAL_SIGNATURE``. See
:doc:`manpages/challenger-send-email.1` and
:doc:`manpages/challenger-send-post.1`.
@@ -317,10 +320,10 @@ provider.
- ``CLICKSEND_USERNAME``, ``CLICKSEND_API_KEY``
* - ``challenger-send-sms-aspsms``
- Switzerland
- - ``ASPSMS_USERKEY``, ``ASPSMS_PASSWORD``
+ - ``ASPSMS_USERKEY``, ``ASPSMS_PASSWORD``, optionally ``ASPSMS_SENDER``
* - ``challenger-send-sms-seven``
- Germany
- - ``SEVEN_API_KEY``
+ - ``SEVEN_API_KEY``, optionally ``SEVEN_SENDER``
* - ``challenger-send-sms-gatewayapi``
- Denmark
- ``GATEWAYAPI_TOKEN``, optionally ``GATEWAYAPI_BASE_URL``
@@ -329,7 +332,7 @@ provider.
- ``BUDGETSMS_USERNAME``, ``BUDGETSMS_USERID``, ``BUDGETSMS_HANDLE``,
optionally ``BUDGETSMS_SENDER``
-Two of the variables above are not credentials:
+Four of the variables above are not credentials:
``GATEWAYAPI_BASE_URL``
Which GatewayAPI platform to use. Optional, defaults to
@@ -338,22 +341,22 @@ Two of the variables above are not credentials:
for an account on the global platform. An API token is only valid on the
platform it was created for.
-``BUDGETSMS_SENDER``
+``ASPSMS_SENDER``, ``SEVEN_SENDER``, ``BUDGETSMS_SENDER``
Sender identity to show on the message, at most 11 alphanumeric or 16
- numeric characters. Optional, defaults to ``Challenger``. The BudgetSMS API
- requires a sender on every message; the other helpers use the sender
- configured on the provider account. Note that an alphanumeric sender has to
- be registered with the operator in a number of countries before messages
- using it are delivered.
-
-Only the first three helpers are listed in ``PROVIDERS`` as shipped. The three
-below them are operated inside the European Economic Area, which avoids
+ numeric characters. Optional; it defaults to ``Taler Ops`` for seven.io and
+ to ``Challenger`` for the other two. The GatewayAPI, Telesign and ClickSend
+ helpers use the sender configured on the provider account. Note that an
+ alphanumeric sender has to be registered with the operator in a number of
+ countries before messages using it are delivered.
+
+As shipped, ``PROVIDERS`` tries ``gatewayapi``, ``budgetsms``, ``aspsms``,
+``seven``, ``telesign`` and ``clicksend``, in this order. GatewayAPI, BudgetSMS
+and seven.io are operated inside the European Economic Area, which avoids
transferring the phone number and the TAN — personal data that is at the same
time an authentication secret — to a third country, and with it the need for a
-transfer instrument under Chapter V of the GDPR. They have been written against
-the published specifications of their APIs and are covered by the offline test
-suite, but have not yet been exercised against a live account, which is why a
-deployment has to enable them explicitly by adding their name to ``PROVIDERS``.
+transfer instrument under Chapter V of the GDPR. With the two of them first, a
+message reaches a provider outside the EEA only when both have failed. To
+change the order or leave a provider out, edit ``PROVIDERS``.
Whether a failing provider causes the next one to be tried depends on the class
of failure: a number that one provider rejects would be rejected by all of