fix: /metrics/history gives the availability of each site-to-site connection as the percentage of time it was up in slots of the view.

ADR.md

@@ -465,11 +465,14 @@ Decision: The package defines its schema, `cn=vpn-router,cn=schema,cn=config`, w
 `vpnrouter_ldap.provision` adds when missing and keeps as `SCHEMA_ATTRIBUTE_TYPES` and
 `SCHEMA_OBJECT_CLASSES`. Its OID is `2.25.98477352595735834532404256531620013001`, made from a
 random UUID under the arc 2.25 (ITU-T X.667), which needs no registration; attribute types are
-under `.1` and object classes under `.2`. The first version has the attribute `vpnRouterScope`
-(multi-valued, case-insensitive strings) and the auxiliary class `vpnRouterAccount`,
-`MAY ( mail $ vpnRouterScope )`. Manager-only accounts have the class from their creation, so an
-e-mail address can be added later without changing their classes; VPN users get it once scopes are
-used.
+under `.1` and object classes under `.2`. It has the attribute `vpnRouterScope` (multi-valued,
+case-insensitive strings) and the auxiliary class `vpnRouterAccount`,
+`MAY ( mail $ vpnRouterScope $ displayName $ description )`; `displayName` and `description`, the
+standard attributes, are the display name and the description of a service account, which
+`account` cannot hold. Manager-only accounts have the class from their creation, so an e-mail
+address can be added later without changing their classes; VPN users get it once scopes are used.
+`vpnrouter_ldap.provision` replaces the definitions in `cn=config` that differ, so an extended class
+reaches an existing directory at the next setup run.
 
 Consequences: The schema check stays strict. New attributes extend `vpnRouterAccount`, and their
 OIDs continue the arcs. The scope `service` marks a service account (ADR-23). The OID must never
@@ -558,7 +561,7 @@ purge. A view shows only what its level keeps, so a shorter retention empties th
 view. A month view needs the hourly rows and a year view the monthly rows. `/metrics` has only the
 last sample; history is not scraped.
 
-## ADR-23: /metrics takes HTTP Basic authentication of an internal service account that setup creates
+## ADR-23: /metrics takes HTTP Basic authentication of an internal service account the router manages
 
 Status: Accepted
 
@@ -567,20 +570,23 @@ the router's tokens, which last minutes (ADR-3). The scraper should not be able
 API or the Manager, and its password should be checked and locked out like any other. The account
 belongs to the package's metrics, not to the people using the router.
 
-Decision: A service account is a Manager-only account (ADR-18) with `vpnRouterScope` `service`.
-Administrators add service accounts with `vpn-router-user add --service` and the web service's
-`/service-accounts`, for services of their own that check passwords against the directory.
+Decision: A service account is a Manager-only account (ADR-18) with `vpnRouterScope` `service`,
+which another system signs in with to use a router service. Administrators add service accounts
+with `vpn-router-user add --service` and the web service's `/service-accounts`.
 `/service-accounts` is a path of its own, apart from `/users`, which does not list or serve them:
 a service account has no names, certificate, profile or TOTP, and is not a person an
-administrator manages with the users. The metrics service's is the internal one, created by
-`vpn-router-setup`: while metrics are enabled it adds the account `metrics.service_account` names,
-`metrics` by default, with a random password it writes to `/etc/vpn-router/metrics.secret` (root
-only), and sets a new random password, ending a lockout, when the file is missing or no longer
-holds the password. `/service-accounts` marks it as `internal` and only lists it: every other
-request on it, and putting it in or taking it out of a group at `/groups`, gets 403, whatever the
-token. Setup
-changes it through the directory's user-manager account, not the API, and root may still with
-`vpn-router-user`. `/auth` refuses every service account with the message of a wrong password. `/metrics` accepts HTTP Basic only for that account, and
+administrator manages with the users. A service account has a display name and a description
+besides its name, so an administrator can tell what each is for. Internal service accounts are
+those the router creates and manages for its own services (`vpnrouter_users.internal_accounts`),
+with every property, display name and description included, so the system, not an
+administrator, owns them; at present that is the metrics service's, which setup names Metrics. `/service-accounts` marks
+them as `internal` and only lists them: every other request on one, and putting one in or taking
+one out of a group at `/groups`, gets 403, whatever the token. The router changes them through the
+directory's user-manager account, not the API, and root may still with `vpn-router-user`. For the
+metrics service, `vpn-router-setup` adds the account `metrics.service_account` names, `metrics` by
+default, while metrics are enabled, with a random password it writes to
+`/etc/vpn-router/metrics.secret` (root only), and sets a new random password, ending a lockout,
+when the file is missing or no longer holds the password. `/auth` refuses every service account with the message of a wrong password. `/metrics` accepts HTTP Basic only for that account, and
 only when it is a service account; the password is checked with a bind as the account, so the
 password policy's lockout applies (ADR-14). TLS is Caddy's, on `metrics.https_port` (ADR-21);
 plain HTTP is served on the interfaces `metrics.listen` names, `internal` by default.

README.md

@@ -393,9 +393,10 @@ is switched on:
   `account` for a Manager-only account (see Managing users);
 - the package's own schema, `cn=vpn-router,cn=schema,cn=config`, under the OID
   `2.25.98477352595735834532404256531620013001` of the UUID arc: the auxiliary class
-  `vpnRouterAccount` with `MAY ( mail $ vpnRouterScope )`, which Manager-only and service accounts
-  have, and the attribute `vpnRouterScope`, authorization scopes, of which `service` marks a
-  service account;
+  `vpnRouterAccount` with `MAY ( mail $ vpnRouterScope $ displayName $ description )`, which
+  Manager-only and service accounts have, and the attribute `vpnRouterScope`, authorization
+  scopes, of which `service` marks a service account; `displayName` and `description` are the
+  display name and the description of a service account;
 - `ou=groups` holds one `groupOfNames` per group, named by `cn`, with its members' DNs in
   `member` and an optional `description`;
 - `cn=user-manager,ou=services` is the account that changes users and groups; it may write
@@ -427,12 +428,16 @@ it is added:
   name, the password and an optional e-mail address, for notifications: no names and no
   certificate, so no VPN access. It can sign in to `/auth` and, as a member of `admins`, manage
   the router. `add` without the first and the last name adds one; its names cannot be set later;
-- a service account, a Manager-only account whose `vpnRouterScope` is `service`, for a service
-  that checks passwords against the directory; it cannot sign in to `/auth`. `add --service` adds
-  one, and the web service manages them at `/service-accounts`, not at `/users`. The internal one
-  is the account `metrics.service_account` names while metrics are enabled: `vpn-router-setup` adds
-  it and keeps its password (see Metrics). The API only lists it: `/service-accounts` refuses every
-  other request on it, and `/groups` refuses to put it in or take it out of a group, with 403.
+- a service account, a Manager-only account whose `vpnRouterScope` is `service`, which another
+  system signs in with to use a router service, such as an OpenTelemetry Collector reading
+  `/metrics`; it cannot sign in to `/auth`. Besides its name, it has a display name and a
+  description. `add --service` adds one, and the web service manages them at `/service-accounts`,
+  not at `/users`. Internal service accounts are those the router creates and manages for its own
+  services, display name and description included; at present that is the metrics service's, the
+  account `metrics.service_account` names while metrics are enabled (see Metrics), which
+  `vpn-router-setup` names Metrics. The API only lists
+  them: `/service-accounts` refuses every other request on one, and `/groups` refuses to put one
+  in or take one out of a group, with 403.
 
 Passwords and TOTP secrets are read from the first line of standard input. The answer is text: a
 table of the users, the client profile, a TOTP secret or a short message, and a failure is a
@@ -464,8 +469,9 @@ vpn-router-user otp-remove alice
 | `list` | The users with their kind, names and e-mail addresses, whether each is enabled or locked, has a certificate and is enrolled for TOTP |
 | `add <name> --first-name F --last-name L --email E` | Adds a VPN user and issues the certificate |
 | `add <name> [--email E]` | Adds a Manager-only account, with the e-mail address when given; one name without the other two options is refused |
-| `add <name> --service [--email E]` | Adds a service account, with the e-mail address when given; the names are refused |
+| `add <name> --service [--display-name N] [--description D] [--email E]` | Adds a service account, with its display name, description and e-mail address when given; the names are refused |
 | `update <name> [--first-name F] [--last-name L] [--email E]` | Changes the names or the e-mail address |
+| `update <name> [--display-name N] [--description D] [--email E]` | Changes the display name, the description or the e-mail address of a service account; `''` removes one |
 | `passwd <name>` | Sets the password |
 | `disable <name>`, `enable <name>` | Locks the user out of OpenVPN and `/auth`, and lets the user in again |
 | `unlock <name>` | Ends a lockout after failed logins and clears the failure count; a disabled user stays disabled |
@@ -750,18 +756,19 @@ curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
 
 | Request | Body | Answer |
 | --- | --- | --- |
-| `GET /service-accounts` | | `{"service_accounts": [{"name", "internal", "enabled", "locked", "email", ...}, ...]}`, each as `/users` shows a user |
-| `POST /service-accounts` | `{"name", "password", "email"?}` | 201 and the account |
-| `PUT /service-accounts/<name>` | `{"email"}`; `""` removes it | the account |
+| `GET /service-accounts` | | `{"service_accounts": [{"name", "display_name", "description", "internal", "enabled", "locked", "email", ...}, ...]}`, each as `/users` shows a user |
+| `POST /service-accounts` | `{"name", "password", "display_name"?, "description"?, "email"?}` | 201 and the account |
+| `PUT /service-accounts/<name>` | any of `{"display_name", "description", "email"}`; `""` removes one | the account |
 | `PUT /service-accounts/<name>/password` | `{"password": ...}` | the account |
 | `POST /service-accounts/<name>/disable` | | the account |
 | `POST /service-accounts/<name>/enable` | | the account |
 | `POST /service-accounts/<name>/unlock` | | the account |
 | `DELETE /service-accounts/<name>` | | `{"name", "removed": true}` |
 
-The internal account, `internal` true, is only listed: every other request on it gets 403, as
-`vpn-router-setup` adds and keeps it. A failure is otherwise as for `/users`, with 404 also for a
-name that is not a service account.
+A display name has at most 64 printable characters and a description at most 256. The internal
+service accounts, `internal` true, are only listed: every other request on one gets 403, as the
+router manages them, their display name and description included. A failure is otherwise as for
+`/users`, with 404 also for a name that is not a service account.
 
 ### The /account API
 
@@ -905,6 +912,17 @@ How it works:
   | `month` | 6 hours | hourly |
   | `year` | 1 month | monthly |
 
+- **Site-to-site availability:** `site_to_site_up` of the same answer divides the view into slots of its own, `slot`, and gives for each slot and connection the percentage of the samples in which the connection was up, 0 to 100, as `points` of `{"time", "connections": {name: percent}}`:
+
+  | Range | Slot | Source |
+  |---|---|---|
+  | `hour` | 5 minutes | details |
+  | `day` | 1 hour | details |
+  | `month` | 1 day | hourly |
+  | `year` | 1 month | monthly |
+
+  A sample is taken every minute, so an interruption shorter than a minute may be missed; a slot without samples has no value, and the year view, like the others of its level, has the complete months only.
+
 ### Scraping
 
 `GET /metrics` of the metrics service serves the last sample in the Prometheus text format, written by `prometheus_client`.

debian-package/debian/changelog

@@ -1,3 +1,47 @@
+vpn-router (0.19.1-1) unstable; urgency=medium
+
+  fix: /metrics/history gives the availability of each site-to-site connection as the percentage of time it was up in slots of the view.
+
+  * site_to_site_up of /metrics/history divides the view into slots of 5
+    minutes for an hour, 1 hour for a day, 1 day for a month and 1 month
+    for a year, and gives for each slot and connection the percentage of
+    the samples in which the connection was up.
+
+ -- Slawomir Koszewski <slawek@koszewscy.waw.pl>  Mon, 26 Oct 2026 21:00:00 +0100
+
+vpn-router (0.19.0-1) unstable; urgency=medium
+
+  feature: service accounts have a display name and a description, which the router sets for its internal ones.
+
+  * vpnRouterAccount of the package's schema also takes displayName and
+    description; vpn-router-setup updates the schema of an existing
+    directory.
+  * /service-accounts shows display_name and description, takes them when
+    adding a service account and changes them with PUT; "" removes one.
+    /users shows them as null.
+  * vpn-router-user add --service and update take --display-name and
+    --description.
+  * vpn-router-setup gives the metrics service's internal account the
+    display name Metrics and its description, and sets them again when
+    they differ.
+
+ -- Slawomir Koszewski <slawek@koszewscy.waw.pl>  Mon, 26 Oct 2026 20:00:00 +0100
+
+vpn-router (0.18.3-1) unstable; urgency=medium
+
+  fix: internal service accounts are the router's own, of which the metrics service's is the one at present, and the documentation says what a service account is.
+
+  * /service-accounts, /groups and the internal field of the answers
+    take every internal service account, the accounts the router creates
+    and manages for its own services, instead of only the metrics
+    service's; the 403 answers say that the router manages them.
+  * The README, the ADR and the users module describe a service account
+    as the account another system, such as an OpenTelemetry Collector
+    reading /metrics, signs in with, and the internal ones as managed by
+    the router.
+
+ -- Slawomir Koszewski <slawek@koszewscy.waw.pl>  Mon, 26 Oct 2026 19:00:00 +0100
+
 vpn-router (0.18.2-1) unstable; urgency=medium
 
   fix: service accounts are managed at /service-accounts, not /users, and the internal one of the metrics service is only listed.

debian-package/src/usr/lib/vpn-router/setup

@@ -458,14 +458,16 @@ def manage_admin():
 def manage_metrics_account(ctx):
     """Keep the service account metrics.service_account names, whose password is in METRICS_SECRET; the problem, or ''.
 
-    While metrics are enabled, setup owns the account: it adds it as a service account with a random password when
-    it is missing, and gives it a new random password, ending any lockout, when METRICS_SECRET is missing or does not
-    hold its password. A disabled account is left as it is. An account of that name that is not a service account is
-    left alone and is a problem.
+    While metrics are enabled, setup owns the account, an internal service account: it adds it as a service account
+    with a random password and the labels of vpnrouter_users.internal_accounts when it is missing, sets those labels
+    when they differ, and gives it a new random password, ending any lockout, when METRICS_SECRET is missing or does
+    not hold its password. The password of a disabled account is left as it is. An account of that name that is not a
+    service account is left alone and is a problem.
     """
     if not vpnrouter.metrics_ready(ctx):
         return ''
     name = ctx['metrics_service_account']
+    wanted = vpnrouter_users.internal_accounts().get(name, {})
     try:
         vpnrouter_users.check_name(name)
         try:
@@ -481,6 +483,8 @@ def manage_metrics_account(ctx):
                 current = None
             if current is not None and not vpnrouter_users.service(current):
                 return f'metrics.service_account: {name} is a user, not a service account'
+            if current is not None and any(vpnrouter_users.summary(current)[key] != value for key, value in wanted.items()):
+                vpnrouter_users.update_service(connection, name, wanted)
             # An administrator who disabled the account meant it; its password is left as it is.
             if current is not None and not vpnrouter_users.summary(current)['enabled']:
                 return ''
@@ -497,7 +501,7 @@ def manage_metrics_account(ctx):
                 METRICS_SECRET.chmod(0o600)
                 METRICS_SECRET.write_text(password + '\n', encoding='utf-8')
                 if current is None:
-                    vpnrouter_users.add(connection, name, password, {}, service=True)
+                    vpnrouter_users.add(connection, name, password, wanted, service=True)
                 else:
                     vpnrouter_users.passwd(connection, name, password)
                     vpnrouter_users.unlock(connection, name)

debian-package/src/usr/lib/vpn-router/vpnrouter_ldap.py

@@ -52,8 +52,9 @@ OVERLAYS = ('ppolicy', 'otp')
 
 #: The package's own schema, under an OID of the UUID arc 2.25 (ITU-T X.667): attribute types
 #: under .1 and object classes under .2. vpnRouterAccount, auxiliary, adds properties of the
-#: package to a user of either kind: mail, for a Manager-only account, and vpnRouterScope,
-#: authorization scopes, of which service marks a service account.
+#: package to a user of either kind: mail, for a Manager-only account, vpnRouterScope,
+#: authorization scopes, of which service marks a service account, and displayName and
+#: description, the labels of a service account.
 SCHEMA_OID = '2.25.98477352595735834532404256531620013001'
 SCHEMA_NAME = 'vpn-router'
 SCHEMA_ATTRIBUTE_TYPES = (
@@ -62,7 +63,7 @@ SCHEMA_ATTRIBUTE_TYPES = (
 )
 SCHEMA_OBJECT_CLASSES = (
     f"( {SCHEMA_OID}.2.1 NAME 'vpnRouterAccount' DESC 'VPN router: properties of a user or a Manager-only account' "
-    "SUP top AUXILIARY MAY ( mail $ vpnRouterScope ) )",
+    "SUP top AUXILIARY MAY ( mail $ vpnRouterScope $ displayName $ description ) )",
 )
 
 #: The TOTP parameters: digits, the OID of HMAC-SHA1, seconds per time step, and the time steps accepted before and after now.

debian-package/src/usr/lib/vpn-router/vpnrouter_metrics.py

@@ -44,6 +44,15 @@ LEVELS = (
 #: The kinds of VPN clients of metrics_vpn.
 VPN_KINDS = ('p2s', 'openvpn', 'wireguard')
 
+#: The time slots of the site-to-site availability of each view of history(): the summary level read (None: the
+#: details), the slot as PostgreSQL starts it from time, and its length.
+UP_SLOTS = {
+    'hour': (None, "date_bin('5 minutes', time, timestamptz '2000-01-01 00:00:00+00')", '5 minutes'),
+    'day': (None, "date_trunc('hour', time, 'UTC')", '1 hour'),
+    'month': ('hourly', "date_trunc('day', time, 'UTC')", '1 day'),
+    'year': ('monthly', "date_trunc('month', time, 'UTC')", '1 month'),
+}
+
 #: The views of history(): the summary level read (None: the details), the bucket and the span.
 RANGES = {
     'hour': (None, '1 minute', '1 hour'),
@@ -148,8 +157,13 @@ def history(connection, view):
     each interface to its rx and tx, clients, which maps each kind of VPN client to its clients,
     and site_to_site, which maps each site-to-site connection to the values of
     metrics_site_to_site; a value without data is None.
+
+    site_to_site_up is the availability of each site-to-site connection in the time slots of UP_SLOTS, oldest first:
+    for each slot its start in Unix seconds and, per connection, the percentage of its samples in which the connection
+    was up, 0 to 100; the summaries' averages of up give it for the month and the year.
     """
     level, bucket, span = RANGES[view]
+    up_level, up_start, up_slot = UP_SLOTS[view]
 
     def rows(table):
         keys, values = TABLES[table]
@@ -182,4 +196,12 @@ def history(connection, view):
     for row in rows('metrics_site_to_site'):
         point(row[0])['site_to_site'][row[1]] = pairs(row[2:], TABLES['metrics_site_to_site'][1])
     empty = {value: {'avg': None, 'max': None} for value in TABLES['metrics_system'][1]}
-    return {'range': view, 'bucket': bucket, 'points': [{**empty, **points[start]} for start in sorted(points)]}
+
+    slots = {}
+    for start, name, percent in connection.execute(
+            f"SELECT extract(epoch FROM {up_start})::bigint AS slot, connection, avg({'up' if up_level is None else 'up_avg'}) * 100 "
+            f"FROM {'metrics_site_to_site' if up_level is None else f'metrics_site_to_site_{up_level}'} "
+            f"WHERE time >= now() - interval '{span}' GROUP BY slot, connection ORDER BY slot").fetchall():
+        slots.setdefault(start, {'time': start, 'connections': {}})['connections'][name] = percent
+    return {'range': view, 'bucket': bucket, 'points': [{**empty, **points[start]} for start in sorted(points)],
+            'site_to_site_up': {'slot': up_slot, 'points': [slots[start] for start in sorted(slots)]}}

debian-package/src/usr/lib/vpn-router/vpnrouter_users.py

@@ -7,10 +7,11 @@ common name, which OpenVPN and IKEv2 accept. A Manager-only account is an accoun
 simpleSecurityObject and vpnRouterAccount (the package's schema) with a name, a password and
 optionally an e-mail address, no names, no certificate and so no VPN access; it is added when
 neither the first nor the last name is given, and can sign in to the web service. A service
-account is a Manager-only account with the scope SERVICE_SCOPE in vpnRouterScope, which cannot
-sign in to the web service; an administrator adds one for a service that checks passwords
-against the directory. The internal one is the account metrics.service_account names while
-metrics are enabled, which vpn-router-setup adds and whose password it keeps (metrics_account).
+account is a Manager-only account with the scope SERVICE_SCOPE in vpnRouterScope, which another
+system signs in with to use a router service, and which cannot sign in to the web service; it has
+a display name and a description (labels), in displayName and description of vpnRouterAccount. The
+internal service accounts are those the router creates and manages for its own services, labels
+included (internal_accounts); vpn-router-setup keeps the metrics service's.
 Users exist whether or not a P2S system is enabled.
 
 A group is a groupOfNames in ou=groups with a name, which follows the rules of user names, an
@@ -65,8 +66,11 @@ EMAIL = re.compile(r'^[^@\s]+@[^@\s]+\.[^@\s]+$')
 EMAIL_MAX = 254
 #: The keys of the person attributes and their LDAP attributes.
 PERSON = (('first_name', 'givenName'), ('last_name', 'sn'), ('email', 'mail'))
+#: The keys of the labels of a service account and their LDAP attributes.
+LABELS = (('display_name', 'displayName'), ('description', 'description'))
 #: The attributes read for a user.
-ATTRIBUTES = ['uid', 'objectClass', 'pwdAccountLockedTime', 'givenName', 'sn', 'mail', 'oathTOTPToken', 'vpnRouterScope']
+ATTRIBUTES = ['uid', 'objectClass', 'pwdAccountLockedTime', 'givenName', 'sn', 'mail', 'oathTOTPToken', 'vpnRouterScope',
+              'displayName', 'description']
 #: The vpnRouterScope of a service account.
 SERVICE_SCOPE = 'service'
 #: The object classes of a VPN user and of a Manager-only account.
@@ -147,6 +151,26 @@ def person(values, required):
     return found
 
 
+def labels(values):
+    """The labels of a service account in values ({display_name, description}), checked, as {LDAP attribute: value}.
+
+    A key whose value is None is not given; '' means none. A display name has at most PERSON_NAME_MAX printable
+    characters and a description at most DESCRIPTION_MAX.
+    """
+    found = {}
+    name = values.get('display_name')
+    if name is not None:
+        if not isinstance(name, str):
+            raise Failure('display_name must be a string', 2)
+        name = name.strip()
+        if len(name) > PERSON_NAME_MAX or any(not character.isprintable() for character in name):
+            raise Failure(f'the display name must have at most {PERSON_NAME_MAX} printable characters', 2)
+        found['displayName'] = name
+    if values.get('description') is not None:
+        found['description'] = check_description(values['description'])
+    return found
+
+
 def dn_of(name):
     return f'uid={name},{vpnrouter_ldap.USERS}'
 
@@ -194,19 +218,26 @@ def service(attributes):
     return SERVICE_SCOPE.encode() in (value.lower() for value in attributes.get('vpnRouterScope', []))
 
 
-def metrics_account():
-    """The internal service account: the one metrics.service_account names while metrics are enabled, else None."""
+def internal_accounts():
+    """The internal service accounts, which the router creates and manages for its own services, by name, each with
+    the labels the router gives it ({display_name, description}): the one metrics.service_account names while metrics
+    are enabled."""
     try:
         metrics = vpnrouter.load_config()['metrics']
     except SystemExit:
-        return None
-    return metrics['service_account'] if metrics['enabled'] else None
+        return {}
+    if not metrics['enabled']:
+        return {}
+    return {metrics['service_account']: {
+        'display_name': 'Metrics',
+        'description': 'The account an OpenTelemetry Collector signs in with to read /metrics of the metrics service.',
+    }}
 
 
 def summary(attributes):
-    """A user as the answers show it; a person attribute the entry does not have is None.
+    """A user as the answers show it; a person attribute or a label the entry does not have is None.
 
-    internal is whether it is the internal service account (metrics_account).
+    internal is whether it is an internal service account (internal_accounts).
     """
     name = attributes['uid'][0].decode()
     lock = attributes.get('pwdAccountLockedTime', [None])[0]
@@ -214,13 +245,13 @@ def summary(attributes):
         'name': name,
         'manager_only': manager_only(attributes),
         'service': service(attributes),
-        'internal': service(attributes) and name == metrics_account(),
+        'internal': service(attributes) and name in internal_accounts(),
         'enabled': lock != LOCKED,
         'locked': lock not in (None, LOCKED) and locked_since(lock) > time.time() - vpnrouter_ldap.LOCKOUT_SECONDS,
         'certificate': certificate(name)[0].is_file(),
         'otp': 'oathTOTPToken' in attributes,
     }
-    for key, attribute in PERSON:
+    for key, attribute in PERSON + LABELS:
         values = attributes.get(attribute)
         user[key] = values[0].decode() if values else None
     return user
@@ -241,12 +272,14 @@ def list_users(connection):
 def add(connection, name, password, values, service=False):
     """Add a user: a VPN user with its certificate when values gives all three person attributes, a Manager-only account
     with at most the e-mail address when it gives neither name, and, with service, a service account, with at most the
-    e-mail address too."""
+    e-mail address and its labels (labels)."""
     check_name(name)
     details = person(values, required=False)
     vpn_user = 'givenName' in details or 'sn' in details
     if service and vpn_user:
         raise Failure('a service account has no first or last name', 2)
+    if service:
+        details.update({attribute: value for attribute, value in labels(values).items() if value})
     if vpn_user and len(details) != len(PERSON):
         raise Failure('give first_name, last_name and email for a VPN user, or at most email for a Manager-only account', 2)
     check_password(password)
@@ -276,9 +309,12 @@ def add(connection, name, password, values, service=False):
 def update(connection, name, values):
     """Change the person attributes values gives; the cn follows the first and the last name.
 
-    A Manager-only account has only the e-mail address, which '' removes.
+    A Manager-only account has only the e-mail address, which '' removes; a service account also its labels
+    (update_service).
     """
     current = entry(connection, name)
+    if service(current):
+        return update_service(connection, name, values)
     if manager_only(current):
         if values.get('first_name') is not None or values.get('last_name') is not None:
             raise Failure(f'user {name} is a Manager-only account, which has no first or last name', 2)
@@ -302,6 +338,21 @@ def update(connection, name, values):
     return summary(entry(connection, name))
 
 
+def update_service(connection, name, values):
+    """Change any of the e-mail address and the labels (labels) of a service account that values gives; '' removes one."""
+    if not service(entry(connection, name)):
+        raise Failure(f'{name} is not a service account', 3)
+    changes = [(ldap.MOD_REPLACE, attribute, [value.encode()] if value else []) for attribute, value in labels(values).items()]
+    email = values.get('email')
+    if email is not None:
+        address = '' if isinstance(email, str) and email.strip() == '' else person({'email': email}, required=False)['mail']
+        changes.append((ldap.MOD_REPLACE, 'mail', [address.encode()] if address else []))
+    if not changes:
+        raise Failure('give email, display_name or description', 2)
+    connection.modify_s(dn_of(name), changes)
+    return summary(entry(connection, name))
+
+
 def passwd(connection, name, password):
     check_password(password)
     entry(connection, name)

debian-package/src/usr/lib/vpn-router/web

@@ -15,7 +15,7 @@ Pages:
            profile, and TOTP enrolment (see users()); service accounts are not among them
   /service-accounts
            the service accounts: list, add, change the e-mail address, set the password,
-           disable, enable, unlock and remove; the internal one is only listed (see
+           disable, enable, unlock and remove; the internal ones are only listed (see
            service_accounts())
   /groups  the groups of the router's directory: list, add, rename or describe, remove, and
            add and take out members (see groups())
@@ -508,16 +508,16 @@ def service_accounts(method, path, body):
     """Answer a /service-accounts request with vpnrouter_users: the HTTP status and the JSON document.
 
       GET    /service-accounts                   the service accounts: {"service_accounts": [...]}
-      POST   /service-accounts                   add one: {"name", "password", "email"?}
-      PUT    /service-accounts/<name>            change the e-mail address: {"email"}; "" removes it
+      POST   /service-accounts                   add one: {"name", "password", "display_name"?, "description"?, "email"?}
+      PUT    /service-accounts/<name>            change any of {"display_name", "description", "email"}; "" removes one
       PUT    /service-accounts/<name>/password   set the password: {"password": ...}
       POST   /service-accounts/<name>/disable    lock it out
       POST   /service-accounts/<name>/enable     let it in again
       POST   /service-accounts/<name>/unlock     end a lockout after failed logins
       DELETE /service-accounts/<name>            remove it
 
-    A name that is not a service account is 404. The internal one (vpnrouter_users.metrics_account), which
-    vpn-router-setup adds and keeps, is only listed: every other request on it is refused with 403.
+    A name that is not a service account is 404. The internal service accounts (vpnrouter_users.internal_accounts),
+    which the router manages, are only listed: every other request on one is refused with 403.
     """
     if body == 'invalid' or (body is not None and not isinstance(body, dict)):
         return 400, {'error': 'the body must be a JSON object'}
@@ -525,13 +525,13 @@ def service_accounts(method, path, body):
     parts = path.strip('/').split('/')
     route = (method, len(parts), parts[2] if len(parts) == 3 else None)
     name = parts[1] if len(parts) > 1 else None
-    email = {'email': body.get('email')}
+    settings = {key: body.get(key) for key in ('email', 'display_name', 'description')}
     actions = {
         ('GET', 1, None): lambda connection: {
             'service_accounts': [user for user in vpnrouter_users.list_users(connection)['users'] if user['service']]},
-        ('POST', 1, None): lambda connection: vpnrouter_users.add(connection, body.get('name'), body.get('password'), email,
+        ('POST', 1, None): lambda connection: vpnrouter_users.add(connection, body.get('name'), body.get('password'), settings,
                                                                   service=True),
-        ('PUT', 2, None): lambda connection: vpnrouter_users.update(connection, name, email),
+        ('PUT', 2, None): lambda connection: vpnrouter_users.update_service(connection, name, settings),
         ('PUT', 3, 'password'): lambda connection: vpnrouter_users.passwd(connection, name, body.get('password')),
         ('POST', 3, 'disable'): lambda connection: vpnrouter_users.disable(connection, name),
         ('POST', 3, 'enable'): lambda connection: vpnrouter_users.enable(connection, name),
@@ -540,8 +540,8 @@ def service_accounts(method, path, body):
     }
     if route not in actions:
         return 404, {'error': f'no route {method} {path}'}
-    if name is not None and name == vpnrouter_users.metrics_account():
-        return 403, {'error': f'{name} is the internal service account of the metrics service; only vpn-router-setup changes it'}
+    if name is not None and name in vpnrouter_users.internal_accounts():
+        return 403, {'error': f'{name} is an internal service account, which the router manages'}
     try:
         with vpnrouter_users.session() as connection:
             if name is not None and not vpnrouter_users.service(vpnrouter_users.entry(connection, name)):
@@ -564,7 +564,7 @@ def groups(state, method, path, body):
       POST   /groups/<name>/members           add a member: {"user": ...}
       DELETE /groups/<name>/members/<user>    take a member out; the last member cannot leave
 
-    The internal service account (vpnrouter_users.metrics_account) is not put in or taken out of a group: such a
+    An internal service account (vpnrouter_users.internal_accounts) is not put in or taken out of a group: such a
     request is refused with 403.
     """
     if body == 'invalid' or (body is not None and not isinstance(body, dict)):
@@ -573,11 +573,12 @@ def groups(state, method, path, body):
     parts = path.strip('/').split('/')
     name = parts[1] if len(parts) > 1 else None
     route = (method, len(parts), parts[2] if len(parts) > 2 else None)
-    internal = vpnrouter_users.metrics_account()
     members = body.get('members') if route == ('POST', 1, None) else [body.get('user')] if route == ('POST', 3, 'members') \
         else [parts[3]] if route == ('DELETE', 4, 'members') else []
-    if internal is not None and isinstance(members, list) and internal in members:
-        return 403, {'error': f'{internal} is the internal service account of the metrics service; only vpn-router-setup changes it'}
+    internal = sorted(set(vpnrouter_users.internal_accounts()).intersection(
+        member for member in (members if isinstance(members, list) else []) if isinstance(member, str)))
+    if internal:
+        return 403, {'error': f'{", ".join(internal)}: internal service accounts, which the router manages, are not group members'}
     actions = {
         ('GET', 1, None): lambda connection: vpnrouter_users.list_groups(connection),
         ('POST', 1, None): lambda connection: vpnrouter_users.group_add(

debian-package/src/usr/sbin/vpn-router-user

@@ -11,8 +11,10 @@ user exists, 1 anything else. -h or --help shows the commands and their options.
   vpn-router-user [--json] list
   vpn-router-user [--json] add <name> --first-name F --last-name L --email E   (password on stdin)
   vpn-router-user [--json] add <name> [--email E]   (a Manager-only account; password on stdin)
-  vpn-router-user [--json] add <name> --service [--email E]   (a service account; password on stdin)
+  vpn-router-user [--json] add <name> --service [--display-name N] [--description D] [--email E]
+                                                  (a service account; password on stdin)
   vpn-router-user [--json] update <name> [--first-name F] [--last-name L] [--email E]
+  vpn-router-user [--json] update <name> [--display-name N] [--description D] [--email E]   (a service account)
   vpn-router-user [--json] passwd <name>       (password on stdin)
   vpn-router-user [--json] disable <name>
   vpn-router-user [--json] enable <name>
@@ -57,7 +59,9 @@ HELP = {
 }
 
 #: The help of the person options.
-PERSON_HELP = {'first_name': 'the first name', 'last_name': 'the last name', 'email': 'the e-mail address'}
+PERSON_HELP = {'first_name': 'the first name', 'last_name': 'the last name', 'email': 'the e-mail address',
+               'display_name': "a service account's display name; '' removes it",
+               'description': "a service account's description; '' removes it"}
 
 
 class Parser(argparse.ArgumentParser):
@@ -76,7 +80,7 @@ def parse(argv):
         if command != 'list':
             sub.add_argument('name', help='the user name')
         if command in ('add', 'update'):
-            for key, _ in vpnrouter_users.PERSON:
+            for key, _ in vpnrouter_users.PERSON + vpnrouter_users.LABELS:
                 sub.add_argument(f'--{key.replace("_", "-")}', dest=key, metavar='TEXT', help=PERSON_HELP[key])
         if command == 'add':
             sub.add_argument('--service', action='store_true', help='add a service account, which cannot sign in to the web service')
@@ -95,7 +99,7 @@ def run(connection, options, secret):
     command = options.command
     if command == 'list':
         return vpnrouter_users.list_users(connection)
-    values = {key: getattr(options, key, None) for key, _ in vpnrouter_users.PERSON}
+    values = {key: getattr(options, key, None) for key, _ in vpnrouter_users.PERSON + vpnrouter_users.LABELS}
     if command == 'add':
         return vpnrouter_users.add(connection, options.name, secret, values, service=options.service)
     if command == 'update':