Documentation updates and fixes

docs/admins/availability-and-migration.rst

@@ -88,6 +88,7 @@ There are several important requirements for this setup:
   ``sources.{name}.authoritative``, ``sources.{name}.nrtm_host``, or
   ``sources.{name}.import_source`` on a standby instance, as these
   conflict with ``readonly_standby``.
+* All instances must run the same IRRD version.
 * It is recommended that all PostgreSQL instances only host the IRRd
   database. Streaming replication will always include all databases,
   and commits received on the standby in any database will trigger

docs/admins/configuration.rst

@@ -226,9 +226,10 @@ General settings
   |br| **Default**: not defined, IRRd does not drop privileges.
   |br| **Change takes effect**: after full IRRd restart.
 * ``secret_key``: a random secret string. **The secrecy of this key protects
-  all web authentication.** If rotated, all sessions and password resets
+  all web authentication.** If rotated, all sessions and tokens in emails
   are invalidated, requiring users to log in or request new password
-  reset links. Second factor authentication is *not* attached to this key.
+  reset links. Rotation will **not** invalidate existing user passwords
+  (only reset links), second factor authentication, or API tokens.
   Minimum 30 characters.
   |br| **Default**: not defined, but required.
   |br| **Change takes effect**: after full IRRd restart.

docs/admins/webui.rst

@@ -4,19 +4,18 @@ Web interface and internal authentication
 Along with HTTP based API calls, GraphQL and the status page, IRRD contains
 a web interface that allows users to migrate their authoritative maintainers
 to an IRRD internal authentication method. It also offers more secure
-override access.
+alternatives to email submissions and override access.
 
 The web interface contains a RPSL submission form, accepting
 the same format as emails, to make object changes. This form accepts
 the new internal authentication as well as passwords, and is meant
-as a more practical and more secure alternative.
+as a more practical and more secure alternative to emails.
 
 The submission form and internal authentication only affect
 objects in authoritative sources.
 
 IRRD internal authentication
 ----------------------------
-
 Traditional maintainer objects authenticate with a list of passwords
 and/or PGP keys in the maintainer object. In IRRD internal authentication,
 the permissions are kept in a separate storage, i.e. not in RPSL
@@ -27,20 +26,27 @@ objects. The major features of internal over traditional are:
   In traditional authentication, anyone with maintainer access can
   essentially take over the maintainer.
 * Users can create API keys with limited permissions, rather than include
-  a password in emails.
+  a password (that allows a full take-over) in emails.
+  API keys are also random, where user passwords are often easier to guess.
 * Users can submit object updates after logging in, without needing
   to pass further authentication.
 * Internal authentication can be combined with traditional, but
   this is not recommended.
 * Logins on the web interface can be protected with two-factor
   authentication.
 * Hashes of (new) user passwords are no longer part of RPSL objects.
+* Users with user management permission can see a log of actions
+  taken on their objects or maintainer, and who performed these actions.
+  This log includes changes made through any submission method.
 * User passwords can not be used directly for authentication of
   e.g. email updates.
 
 You can allow migrations with the
 ``auth.irrd_internal_migration_enabled`` setting.
 By default, this is disabled.
+Even with migration disabled, users can use the object submission
+interface to submit in the same format as email, by including the
+``password`` or ``override`` pseudo-attributes.
 
 Override access
 ---------------
@@ -74,13 +80,14 @@ the ``irrdctl user-mfa-clear`` command.
 
 Maintainer migration
 --------------------
-Migrating a maintainer can be done by any registered user, and involves
+Migrating a maintainer can be done by any registered user when
+``auth.irrd_internal_migration_enabled`` is enabled, and involves
 the following steps:
 
 * The user requests migration with the maintainer name and one of the
   current valid passwords on the maintainer.
-* IRRD will mail all admin-c contacts on the maintainer with a
-  confirmation link.
+* IRRD will mail all `admin-c` contacts on the maintainer with the
+  confirmation link (all will receive the same link).
 * The same user must open the confirmation link, and confirm again with
   a current valid password.
 * The maintainer is now migrated. Existing methods are kept.

docs/releases/4.4.0.rst

@@ -10,6 +10,62 @@ as of 27 June 2023 and therefore no longer supported.
 .. _end of life: https://endoflife.date/python
 
 
+IRRD internal authentication
+----------------------------
+IRRD 4.4 contains a new web interface (on ``/ui/``)
+that allows users to migrate their authoritative maintainers
+to an IRRD internal authentication method. This allows removal of
+hashes from RPSL `mntner` objects and much more granular access
+control.
+
+The new web interface also offers
+more secure alternatives to email submissions and override access,
+independent of whether you choose to allow maintainer migrations.
+
+You can allow maintainer migrations with the
+``auth.irrd_internal_migration_enabled`` setting.
+By default, this is disabled.
+Even with migration disabled, users can use the object submission
+interface to submit in the same format as email, by including the
+``password`` or ``override`` pseudo-attributes.
+
+For full details, see the
+:doc:`web interface and internal authentication documentation </admins/webui/>`
+
+This new feature adds two new required settings, with no default set:
+
+* ``secret_key``, which must be a random secret string, used to protect
+  session data and tokens in emails.
+* ``server.http.url``, which must be the external URL on which users will
+  reach the IRRD instance, used for WebAuthn second factor authentication.
+  This must match the URL as seen from the browser's perspective,
+  and changing it will invalidate all WebAuthn tokens.
+
+
+New recommendations on availability and replication
+---------------------------------------------------
+Historically, operators have used different methods for synchronising
+an active instance of IRRD with a standby, or doing migrations.
+Some of these had issues around serial synchronisation, object suppression, or
+update frequency.
+
+There is now one recommended method for synchronisation between IRRD 4 instances,
+and new documentation on
+:doc:`availability with PostgreSQL replication </admins/availability-and-migration>`
+including specific required PostgreSQL settings.
+
+The ``database_readonly`` setting was removed, in favour of a new
+``readonly_standby`` setting. These settings are similar but have some
+differences, and this is an intentional breaking change as you will need
+specific PostgreSQL configuration for this to work correctly.
+
+If you use any kind of availability/standby setup, you should review
+this documentation and switch to the new recommended setup.
+
+Note that, although most of the work is done by PostgreSQL,
+IRRD 4.4 does have new internal handling to support this replication
+method. This means you can not apply this to IRRD prior to 4.4.
+
 Upgrading to IRRd 4.4.0 from 4.3.x
 ----------------------------------
 TODO