ldap-rest 1.1.0 → 1.2.0

package/dist/src/plugins/storage.d.ts

@@ -30,10 +30,18 @@
 import DmPlugin from '../abstract/plugin';
 import type { DM } from '../bin';
 import type Store from '../lib/storage/store';
+import type { HealthStatus } from '../lib/health';
 export default class Storage extends DmPlugin {
     name: string;
     store: Store;
     constructor(server: DM);
+    close(): Promise<void>;
+    /** Set while the backend fails the probe, so the reason is logged once */
+    private degraded;
+    /** Counts the probes: only the latest says what the log lines say */
+    private probes;
+    /** The backend's own answer; a backend that cannot answer is degraded */
+    health(): Promise<HealthStatus>;
     /**
      * Release the single-instance hold.
      *

package/dist/src/plugins/twake/drive.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Twake Drive Plugin
+ *
+ * Synchronizes LDAP user changes with Twake Drive via Admin API.
+ * Propagates email address, display name, and disk quota changes.
+ *
+ * @see https://docs.cozy.io/en/cozy-stack/admin/
+ */
 import TwakePlugin from '../../abstract/twakePlugin';
 import { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';

package/dist/src/plugins/twake/james.d.ts

@@ -1,5 +1,6 @@
 import type { Express } from 'express';
 import TwakePlugin from '../../abstract/twakePlugin';
+import type { HealthStatus } from '../../lib/health';
 import { type Role } from '../../abstract/plugin';
 import type { DM } from '../../bin';
 import type { AttributeValue } from '../../lib/ldapActions';
@@ -22,6 +23,7 @@ export default class James extends TwakePlugin {
         onLdapChange: string;
         ldapGroups: string;
     };
+    health(): Promise<HealthStatus>;
     private quotaAttr;
     private aliasAttr;
     private mailboxTypeAttr;

package/dist/src/plugins/twake/migrationProxy.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module plugins/twake/migrationProxy
+ *
+ * Keeps the migrated-users list of the Twake Mail migration proxy in step
+ * with the accounts of the directory: an account created during the
+ * migration has no mailbox on the old system, so the proxy has to route it
+ * to the new one from its first login, and the addresses of a migrated
+ * account have to follow it.
+ *
+ * See `docs/usage/plugins/integrations/mail-migration.md`.
+ */
+import type { Express } from 'express';
+import TwakePlugin from '../../abstract/twakePlugin';
+import { type Role } from '../../abstract/plugin';
+import type { DM } from '../../bin';
+import type { Hooks } from '../../hooks';
+import type { HealthStatus } from '../../lib/health';
+/**
+ * @openapi
+ * components:
+ *   schemas:
+ *     MailMigrationStatus:
+ *       type: object
+ *       required: [migrated]
+ *       properties:
+ *         migrated:
+ *           type: boolean
+ *           description: Whether the proxy routes the user to the new backend
+ */
+export default class MigrationProxy extends TwakePlugin {
+    name: string;
+    roles: Role[];
+    dependencies: {
+        onLdapChange: string;
+    };
+    private readonly branches;
+    private readonly aliasAttr;
+    /** The work on one entry waits for the work before it */
+    private readonly queues;
+    constructor(server: DM);
+    health(): Promise<HealthStatus>;
+    api(app: Express): void;
+    hooks: Hooks;
+    /**
+     * One entry at a time: two writes close together would otherwise race to
+     * the proxy, the second reading a list the first has not written yet
+     */
+    private inOrder;
+    /**
+     * The address the entry logs in with, and the ones that reach it, each
+     * once: an alias repeating the mail would otherwise be put and taken off
+     * in the same breath
+     */
+    private addresses;
+    /**
+     * An entry gaining its address is put on the list with all of them, one
+     * losing it is taken off; one keeping it has its addresses follow it when
+     * the proxy says it is migrated, and is left to the migration otherwise.
+     * The proxy folds usernames to lower case, so a change of case is none.
+     */
+    private follow;
+    private userUrl;
+    private call;
+    /**
+     * `HEAD /migratedUsers/{user}`: 204 when migrated, 404 otherwise. With
+     * `retry`, an answer of {@link PROXY_UNAVAILABLE} is asked again as a
+     * write would be; throws once the proxy has not said
+     */
+    isMigrated(address: string, retry?: boolean): Promise<boolean>;
+    private getMigrationStatus;
+}

package/docs/client-development/api/reference.md

@@ -93,11 +93,13 @@ Complete technical reference for the LDAP-Rest REST API including detailed speci
 | 500  | Internal Server Error | Server-side failure            | LDAP connection issues, database errors, plugin failures |
 | 503  | Service Unavailable   | Server temporarily unavailable | LDAP server down, maintenance mode                       |
 
-**Example 500 Response:**
+**Example 500 Response** (the failure is in the server's logs; `message`
+names it only when the server runs with `--debug`):
 
 ```json
 {
-  "error": "LDAP bind error"
+  "error": "Internal Server Error",
+  "message": "An error occurred"
 }
 ```
 
@@ -805,13 +807,7 @@ Failed to fetch
 
 #### Problem: LDAP Connection Failed
 
-**Error:**
-
-```json
-{
-  "error": "LDAP bind error"
-}
-```
+**Error:** a 500 answer, with `LDAP bind error` in the server's logs.
 
 **Checklist:**
 

package/docs/client-development/api/rest-api.md

@@ -1335,19 +1335,13 @@ no `limit` was given —
 
 #### 500 Internal Server Error
 
-**LDAP Connection Error:**
+The failure is in the server's logs, not in the response; the message names
+it only when the server runs with `--debug`:
 
 ```json
 {
-  "error": "LDAP bind error"
-}
-```
-
-**General Server Error:**
-
-```json
-{
-  "error": "Internal server error: <details>"
+  "error": "Internal Server Error",
+  "message": "An error occurred"
 }
 ```
 

package/docs/client-development/schemas/README.md

@@ -169,7 +169,10 @@ This will be replaced with the actual LDAP base at runtime (e.g., `ou=users,dc=e
 
 ## Attribute Types
 
-LDAP-Rest supports three main attribute types: `string`, `array`, and `pointer`.
+LDAP-Rest supports three main attribute types: `string`, `array`, and `pointer`,
+plus `number`, `integer`, `boolean` and `date` for single values. What a
+client sends has to have the shape of the type, see
+[what a value must look like](#what-a-value-must-look-like).
 
 ### String Type
 
@@ -337,7 +340,7 @@ Complete reference for all attribute properties.
 
 | Property   | Type            | Applies To          | Description                                                                           | Example                             |
 | ---------- | --------------- | ------------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
-| `type`     | string          | All                 | Attribute data type: `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`      | `"string"`                          |
+| `type`     | string          | All                 | `"string"`, `"array"`, `"pointer"`, `"number"`, `"integer"`, `"boolean"`, `"date"`    | `"string"`                          |
 | `required` | boolean         | All                 | Whether the attribute must be present                                                 | `true`                              |
 | `fixed`    | boolean         | All                 | Whether the attribute value cannot be changed after creation                          | `true`                              |
 | `role`     | string/string[] | String              | Semantic role, or roles, for special handling (see [Semantic Roles](#semantic-roles)) | `"identifier"`                      |
@@ -364,6 +367,32 @@ Defines the data type of the attribute. Supported values:
 - `"pointer"`: Reference to another LDAP entry (DN)
 - `"number"`: Numeric value (integer or float)
 - `"integer"`: Integer value only
+- `"boolean"`: `true` or `false`, stored as `TRUE` / `FALSE`
+- `"date"`: LDAP generalized time, as text
+
+#### What a value must look like
+
+A single-valued attribute takes one value, an `array` a list. A list of one
+value stands for that value and one value for a list of one, so what a read
+answers, one value where the attribute holds one, can be sent back as is;
+two values or more for a single-valued attribute are refused. Each element
+of an `array` follows `items.type`, text without `items`. A `number` or
+`integer` is a JSON number or its text (`42`, `"42"`), a `boolean` a JSON
+boolean or the directory's `TRUE` / `FALSE`; anything else for them, and
+anything but text for a `string`, `date` or `pointer`, is refused; an
+attribute with `normalize` takes any text, read after validation. In a
+`replace`, `null` or `[]` clears an attribute; in an `add` or on a creation
+they are refused as no value. A `delete` naming the attribute, or naming it
+with no value, removes it, unless it is `required`; naming values removes
+those, every value it holds included, as the server does not read what
+remains, and `''` names no value. An empty string sent as a value is
+checked against `test`, refused for a pointer, and missing for a `required`
+attribute. Every refusal answers 400 with the attribute's name.
+
+Every entity route applies these rules; `test/lib/entitySchema.contract.test.ts`
+asserts them on a flat entity, a group and an organization alike. In the
+server they are enforced by `EntityValidator` (`src/lib/entitySchema/validator.ts`)
+alone: ESLint refuses the import of the schema helpers anywhere else.
 
 #### `required` (Optional, default: `false`)
 
@@ -674,13 +703,8 @@ Common validation patterns:
 
 ### Type Validation
 
-Attribute values must match their declared type:
-
-- **String**: Single text value
-- **Array**: Multiple values (may be empty unless required)
-- **Number**: Numeric value (integer or float)
-- **Integer**: Integer value only
-- **Pointer**: Valid DN string
+Attribute values must have the shape of their declared type, see
+[what a value must look like](#what-a-value-must-look-like).
 
 ### Fixed Attributes
 
@@ -780,6 +804,7 @@ twake/
 ```bash
 npx ldap-rest \
   --ldap-base 'dc=example,dc=com' \
+  --ldap-dn 'cn=admin,dc=example,dc=com' --ldap-pwd secret \
   --plugin core/ldap/flatGeneric \
   --ldap-flat-schema ./static/schemas/twake/users.json \
   --plugin core/ldap/groups \
@@ -842,6 +867,7 @@ ad/
 ```bash
 npx ldap-rest \
   --ldap-base 'dc=example,dc=com' \
+  --ldap-dn 'cn=admin,dc=example,dc=com' --ldap-pwd secret \
   --plugin core/ldap/flatGeneric \
   --ldap-flat-schema ./static/schemas/ad/users.json \
   --plugin core/ldap/groups \
@@ -910,6 +936,7 @@ standard/
 ```bash
 npx ldap-rest \
   --ldap-base 'dc=example,dc=com' \
+  --ldap-dn 'cn=admin,dc=example,dc=com' --ldap-pwd secret \
   --plugin core/ldap/flatGeneric \
   --ldap-flat-schema ./static/schemas/standard/users.json \
   --plugin core/ldap/groups \
@@ -1055,6 +1082,7 @@ Save your schema and reference it when starting LDAP-Rest:
 ```bash
 npx ldap-rest \
   --ldap-base 'dc=example,dc=com' \
+  --ldap-dn 'cn=admin,dc=example,dc=com' --ldap-pwd secret \
   --plugin core/ldap/flatGeneric \
   --ldap-flat-schema ./path/to/custom-users.json
 ```
@@ -1131,18 +1159,29 @@ it with a 500.
 ### Served Schemas
 
 `core/static` serves the merged schema. The configuration API gives each
-entity its merged schema inline (`schema`) and, with `core/static`, a
-`schemaUrl` made of the file path from its first `schemas` directory:
-`/etc/ldap-rest/schemas/users.json` gets `/static/schemas/users.json`.
-`core/static` serves a configured schema file at that URL even when it is
-outside `--static-path`, and before a shipped schema of the same URL:
-`/etc/ldap-rest/schemas/twake/users.json` is what
-`/static/schemas/twake/users.json` returns. An option left at its default
-does not count: without `--group-schema`, a `--static-path` of your own
-still serves its `schemas/twake/groups.json`. If two configured files get
-the same URL, the first one is served there and a warning names the other.
-A file outside any `schemas` directory has no `schemaUrl`; its schema is
-still inline.
+entity its merged schema inline (`schema`) and, where a static plugin's
+schema routes serve that very file, its `schemaUrl`, under the plugin's own
+`--static-name`:
+
+- a schema file of the configuration gets the file path from its first
+  `schemas` directory, `/etc/ldap-rest/schemas/users.json` getting
+  `/static/schemas/users.json`. `core/static` serves it at that URL even
+  when it is outside `--static-path`, and before a shipped schema of the
+  same URL: `/etc/ldap-rest/schemas/twake/users.json` is what
+  `/static/schemas/twake/users.json` returns. If two configured files get
+  the same URL, the first one is served there and a warning names the
+  other;
+- a file the `schemas/` directory of `--static-path` holds, that directory
+  being a link or not, gets its path in it, if it is named `.json`.
+
+An option left at its default does not count as configured: without
+`--group-schema`, a `--static-path` of your own still serves its
+`schemas/twake/groups.json`, and no `schemaUrl` is given unless that file is
+the package's, through a link. A static plugin loaded under another name, or with a
+`static_name` of its own, is asked as well, the one registered as `static`
+first. A file no static plugin serves merged has no `schemaUrl`, one
+express.static would send as it stands included (outside `schemas/`, or not
+named `.json`); its schema is still inline.
 
 ---
 

package/docs/plugin-development/README.md

@@ -61,20 +61,22 @@ export default class MyPlugin extends DmPlugin {
 - **this.config**: Complete configuration object
 - **this.logger**: Winston logger instance
 - **this.registeredHooks**: Access to global hook registry
+- **this.fetch**: `fetch` timed into the
+  [outbound metrics](../usage/operations.md#metrics) under the plugin's
+  name; the lint refuses a bare `fetch` or `node-fetch` under `src`, and a
+  plugin with a `fetch` member of its own has to rename it
 
 ### Error Handling and Server Resilience
 
-LDAP-Rest includes robust error handling to ensure the server remains operational even when plugins encounter errors:
-
-#### Global Error Handling
-
-The server automatically catches and handles:
-
-- **Uncaught exceptions** in plugin code
-- **Unhandled promise rejections**
-- **Errors in async route handlers**
-
-All errors are logged with full stack traces without crashing the server.
+An error a route handler or a hook throws is logged with its stack; the
+request is answered with a 5xx when the hook ran before the operation, and
+the server keeps serving. An exception nothing catches, in a timer or an
+event handler, is not: the binary shuts down and exits with 1, and a
+promise rejection nothing handles is logged and counted, see
+[shutdown](../usage/operations.md#shutdown); a host assembling the server
+chooses with `exitOnCrash()`. A plugin holding a connection, a timer or a
+queue implements `close()`, see
+[for plugin authors](../usage/operations.md#for-plugin-authors).
 
 #### Using asyncHandler
 
@@ -175,7 +177,7 @@ export default class WebhookNotifier extends DmPlugin {
   // Private methods
   private async sendWebhook(event: string, data: unknown): Promise<void> {
     try {
-      await fetch(this.config.webhook_url as string, {
+      await this.fetch(this.config.webhook_url as string, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ event, data }),
@@ -1153,7 +1155,7 @@ export default class NotificationPlugin extends DmPlugin {
     const timeoutId = setTimeout(() => controller.abort(), this.webhookTimeout);
 
     try {
-      const response = await fetch(this.webhookUrl, {
+      const response = await this.fetch(this.webhookUrl, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',

package/docs/plugin-development/dependencies.md

@@ -204,6 +204,14 @@ overrides builds a second instance, and it needs a name of its own.
 - **Consumes Hooks**: (Hooks provided by `onLdapChange`)
 - **Notes**: Synchronizes LDAP users/groups with Apache James mail server
 
+#### `migrationProxy` (twake/migrationProxy)
+
+- **Dependencies**:
+  - `onLdapChange: 'core/ldap/onChange'` ⚠️ **Required**
+- **Provides Hooks**: None
+- **Consumes Hooks**: `onLdapEntryChange` (provided by `onLdapChange`)
+- **Notes**: Keeps the migrated-users list of the Twake Mail migration proxy, see [mail-migration](../usage/plugins/integrations/mail-migration.md)
+
 #### `calendar` (twake/calendar)
 
 - **Dependencies**:

package/docs/plugin-development/hooks.md

@@ -9,7 +9,7 @@ those typed in [hooks.ts](../../src/hooks.ts), which is the reference.
 
 ## [LDAP](../../src/lib/ldapActions.ts) hooks
 
-- **ldapopts**: called before any ldapsearch to modify search options
+- **ldapsearchopts**: called before any ldapsearch to modify search options
 - **ldapsearchresult**: called after any ldapsearch to modify search result
 - **ldapaddrequest**: called before any ldapadd
 - **ldapadddone**: launched once an ldapadd has written the entry, not awaited

package/docs/usage/README.md

@@ -88,4 +88,5 @@ The system will:
 - **[Plugins](plugins/README.md)** - Choose and configure plugins
 - **[Upgrading](upgrading.md)** - What to check before deploying a new version
 - **[Directory audit](directory-audit.md)** - What a schema would refuse in an existing directory
+- **[Operations](operations.md)** - Health and readiness probes
 - **[Troubleshooting](troubleshooting.md)** - Problem resolution

package/docs/usage/configuration.md

@@ -39,17 +39,20 @@ All LDAP-Rest configuration options.
     - [core/auth/trustedProxy](#coreauthtrustedproxy)
   - [Twake Integration Plugins](#twake-integration-plugins)
     - [core/twake/james](#coretwakejames)
+    - [core/twake/migrationProxy](#coretwakemigrationproxy)
     - [core/twake/calendar](#coretwakecalendar)
     - [core/twake/applicativeAccounts](#coretwakeapplicativeaccounts)
     - [core/twake/appAccountsConsistency](#coretwakeappaccountsconsistency)
   - [Utility Plugins](#utility-plugins)
     - [core/static](#corestatic)
     - [core/weblogs](#coreweblogs)
+    - [core/metrics](#coremetrics)
     - [core/storage](#corestorage)
     - [core/configApi](#coreconfigapi)
 - [Configuration File](#configuration-file)
 - [LDAP Failover](#ldap-failover)
 - [Log Levels (`--log-level`)](#log-levels---log-level)
+- [Logger (`--logger`)](#logger---logger)
 
 ## Environment Variables
 
@@ -148,15 +151,18 @@ to keep the default.
 
 ## General Options
 
-| CLI              | Plural           | Env               | Default          | Description                                 |
-| ---------------- | ---------------- | ----------------- | ---------------- | ------------------------------------------- |
-| `--port`         |                  | `DM_PORT`         | `8081`           | Listen port                                 |
-| `--plugin`       | `--plugins`      | `DM_PLUGINS`      | `[]`             | Plugins to load                             |
-| `--log-level`    |                  | `DM_LOG_LEVEL`    | `notice`         | Log level: error, warn, notice, info, debug |
-| `--logger`       |                  | `DM_LOGGER`       | `console`        | Logger type                                 |
-| `--api-prefix`   |                  | `DM_API_PREFIX`   | `/api`           | API URL prefix                              |
-| `--mail-domain`  | `--mail-domains` | `DM_MAIL_DOMAIN`  | `[]`             | Mail domains                                |
-| `--schemas-path` |                  | `DM_SCHEMAS_PATH` | `static/schemas` | Path to JSON schemas                        |
+| CLI                  | Plural           | Env                   | Default          | Description                                                                                       |
+| -------------------- | ---------------- | --------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
+| `--port`             |                  | `DM_PORT`             | `8081`           | Listen port                                                                                       |
+| `--shutdown-timeout` |                  | `DM_SHUTDOWN_TIMEOUT` | `20000`          | How long a stop may take, in ms, see [shutdown](operations.md#shutdown)                           |
+| `--plugin`           | `--plugins`      | `DM_PLUGINS`          | `[]`             | Plugins to load                                                                                   |
+| `--log-level`        |                  | `DM_LOG_LEVEL`        | `notice`         | Log level: error, warn, notice, info, debug                                                       |
+| `--logger`           |                  | `DM_LOGGER`           | `console`        | `console` or `file`, see [Logger](#logger---logger)                                               |
+| `--log-file`         |                  | `DM_LOG_FILE`         | `error.log`      | File `--logger file` writes to                                                                    |
+| `--debug`            |                  | `DM_DEBUG`            | `false`          | Name the failure in the 5xx answers of the error middleware and `serverError`; not for production |
+| `--api-prefix`       |                  | `DM_API_PREFIX`       | `/api`           | API URL prefix                                                                                    |
+| `--mail-domain`      | `--mail-domains` | `DM_MAIL_DOMAIN`      | `[]`             | Mail domains                                                                                      |
+| `--schemas-path`     |                  | `DM_SCHEMAS_PATH`     | `static/schemas` | Path to JSON schemas                                                                              |
 
 A schema file named by an option may extend another one, shipped or not, and
 hold only the differences:
@@ -167,8 +173,8 @@ hold only the differences:
 | CLI                          | Plural           | Env                      | Default                            | Description                                 |
 | ---------------------------- | ---------------- | ------------------------ | ---------------------------------- | ------------------------------------------- |
 | `--ldap-url`                 | `--ldap-urls`    | `DM_LDAP_URL`            | `ldap://localhost`                 | LDAP server URL(s)                          |
-| `--ldap-dn`                  |                  | `DM_LDAP_DN`             | `cn=admin,dc=example,dc=com`       | Bind DN                                     |
-| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            | `admin`                            | Password                                    |
+| `--ldap-dn`                  |                  | `DM_LDAP_DN`             |                                    | Bind DN (required)                          |
+| `--ldap-pwd`                 |                  | `DM_LDAP_PWD`            |                                    | Password (required)                         |
 | `--ldap-base`                |                  | `DM_LDAP_BASE`           |                                    | Base DN for searches (required)             |
 | `--ldap-user-main-attribute` |                  | `DM_LDAP_USER_ATTRIBUTE` | `uid`                              | User identifier attribute                   |
 | `--ldap-cache-max`           |                  | `DM_LDAP_CACHE_MAX`      | `1000`                             | Max cache entries                           |
@@ -493,6 +499,19 @@ whichever of the two names it selects. A value other than `req.user` or
 
 The wait before each retry grows with the attempt, so the total wait is `--james-retry-delay` × n(n−1)/2 for n attempts: 10 s with the defaults, 190 s with 20 attempts.
 
+#### `core/twake/migrationProxy`
+
+Keeps the migrated-users list of the Twake Mail migration proxy in step with the accounts, [details](plugins/integrations/mail-migration.md).
+
+| CLI                                | Plural                       | Env                                 | Default | Description                                                      |
+| ---------------------------------- | ---------------------------- | ----------------------------------- | ------- | ---------------------------------------------------------------- |
+| `--migration-proxy-url`            |                              | `DM_MIGRATION_PROXY_URL`            |         | Webadmin URL of the proxy (required)                             |
+| `--migration-proxy-token`          |                              | `DM_MIGRATION_PROXY_TOKEN`          |         | Bearer token                                                     |
+| `--migration-proxy-branch`         | `--migration-proxy-branches` | `DM_MIGRATION_PROXY_BRANCHES`       | `[]`    | Branches whose entries are followed, `;`-separated (required)    |
+| `--migration-proxy-concurrency`    |                              | `DM_MIGRATION_PROXY_CONCURRENCY`    | `10`    | Calls to the proxy at once                                       |
+| `--migration-proxy-retry-attempts` |                              | `DM_MIGRATION_PROXY_RETRY_ATTEMPTS` | `5`     | Attempts in all of a call the proxy answers 500, 502, 503 or 504 |
+| `--migration-proxy-retry-delay`    |                              | `DM_MIGRATION_PROXY_RETRY_DELAY`    | `1000`  | Base retry delay (ms), growing with the attempt                  |
+
 #### `core/twake/calendar`
 
 Formerly `core/twake/calendarResources`, still accepted as a deprecated alias.
@@ -675,6 +694,15 @@ See [security headers](plugins/utilities/static.md#security-headers).
 
 Web access logging plugin. No configuration options - just add the plugin to enable access logs.
 
+#### `core/metrics`
+
+Prometheus metrics on a port of their own, see
+[metrics](operations.md#metrics).
+
+| CLI              | Env               | Default | Description                                                |
+| ---------------- | ----------------- | ------- | ---------------------------------------------------------- |
+| `--metrics-port` | `DM_METRICS_PORT` | `9464`  | Port `GET /metrics` is served on; keep it off the internet |
+
 #### `core/storage`
 
 Keyed storage with a deadline, for the plugins that need to keep something —
@@ -743,3 +771,13 @@ The system will:
 | `debug`  | Everything, including debug output           |
 
 The `notice` level is ideal for production as it shows web access logs without flooding with general info messages.
+
+## Logger _(`--logger`)_
+
+| Logger    | Output                                                                                               |
+| --------- | ---------------------------------------------------------------------------------------------------- |
+| `console` | One JSON object per line on standard output (errors and warnings on standard error)                  |
+| `file`    | Text lines appended to `--log-file` (`DM_LOG_FILE`), `error.log` in the working directory by default |
+
+An empty value is `console`. Any other value, or `file` with an empty
+`--log-file`, stops the server at startup.