Documentation improvements

docs/releases/4.5.0.rst

@@ -123,3 +123,50 @@ Other changes
 
 .. _the answer size in the A response was wrong: https://github.com/irrdnet/irrd/issues/1019
 .. _be incorrectly indexed and displayed in !g/!6/!a queries: https://github.com/irrdnet/irrd/issues/1014
+
+
+Upgrading to IRRd 4.5.0 from 4.4.x
+----------------------------------
+As with any other major IRRd release, depending on the availability
+needs of your setup, it is recommended to first thoroughly test the upgrade
+and operation on a testing/acceptance setup with similar data size.
+
+The recommended steps to upgrade are:
+
+* Read the release notes above, particularly for any settings
+  you may want to change.
+* Make sure your Python (minimum 3.10) version is recent enough.
+* Stop the IRRd process.
+* Upgrade the IRRd package. If using pipx, run ``pip install irrd==4.5.0``.
+  If using a manual virtualenv, from within the virtualenv, run:
+  ``pip install irrd==4.5.0``
+* Run the database migrations, using the
+  :ref:`irrd_database_upgrade <deployment-database-upgrade>` command.
+  The migrations modify only status tables, and should be fairly quick.
+* Restart IRRd.
+* If you run an authoritative database, you are recommended to enable
+  the NRTMv4 server. If you mirror from others, NRTMv4 is now recommended
+  over NRTMv3 where available.
+  See the :doc:`mirroring documentation </users/mirroring>` for details.
+
+It should be safe to keep cron and e-mail triggered tasks active
+during the upgrade, but during installation, tasks may fail.
+To prevent this, disable these during the upgrade.
+
+Downgrading from 4.5 to 4.4.x
+-----------------------------
+If you are running IRRd 4.5, and would like to downgrade back to 4.4.x,
+the database schema needs to be modified. You can either restore an older
+copy of your database, start with a fresh database, or use the database
+migrations.
+
+If you want to use the database migrations, run this command **before**
+downgrading your local package installation to 4.4.x::
+
+    irrd_database_downgrade --version 2353e60e63f8
+
+Note that any NRTMv4 status will be lost.
+
+If you would like to re-upgrade to 4.5 later on, you will need to run
+the database migrations again, as listed in the upgrade steps.
+

docs/users/mirroring.rst

@@ -104,24 +104,27 @@ which IRRD will create in the provided path. You can serve them
 using the same nginx instance used for other parts of IRRD,
 or through an entirely different web server or CDN, depending on your
 scalability needs. So in a way, the actual "serving" part of an
-NRTMv4 server is not performed by IRRD, as it's just static files over HTTPS.
+NRTMv4 server is not performed by IRRD, it only produces files for you
+to serve over HTTPS
 
 NRTMv4 has support for in-band key rotation. Use the following process:
 
 * Generate a new private key.
-* Save the new key in ``nrtm4_server_private_key_next`` on the source.
+* Save the new key in the ``nrtm4_server_private_key_next`` setting
+  for your authoritative source.
 * IRRD will automatically add the public key to the ``next_signing_key``
   field in the Update Notification File.
 * On their next update of the Update Notification File, clients will
   see the next key, and store it.
-* After some time (recommended: one week), set the new key in
-  ``nrtm4_server_private_key`` and remove ``nrtm4_server_private_key_next``.
+* After some time (recommended: one week), set the new key in the
+  ``nrtm4_server_private_key`` setting and remove
+  ``nrtm4_server_private_key_next``.
 * Key rotation is now complete.
 
 The private key(s) stored in your IRRD configuration should never be
 shared publicly. Clients should only have the public key.
 At any time you can use the ``irrdctl nrtmv4 server-show-public-key``
-command to see the public key of the configured private key(s).
+command to see the public key for the configured private key(s).
 
 
 NRTMv3 mode
@@ -208,24 +211,25 @@ A single source can only use one mirroring mode.
 
 NRTMv4 mode
 ~~~~~~~~~~~
-To configure an NRTMv4 source, you set the ``nrtm4_client_notification_file_url``
+To configure an NRTMv4 source, set the ``nrtm4_client_notification_file_url``
 setting on the source to the Update Notification File URL.
-and the ``nrtm4_client_notification_file_url`` setting to the initial public key.
-Both of these will be published by the mirror server operator.
+and the ``nrtm4_client_notification_file_url`` setting to the initial public key
+(in PEM format). Both of these will be provided by the mirror server operator.
 
 When running the NRTMv4 client process, IRRD will:
 
 * Retrieve and validate the Update Notification File and its signature.
 * Check if the force reload flag was set by the ``irrd_mirror_force_reload`` command,
-  if so, IRRD reloads from snapshot.
+  if so, IRRD reloads from the snapshot.
 * Check if the session ID is the same as previously known. If not,
-  IRRD reloads from snapshot.
+  IRRD reloads from the snapshot.
 * Check if there is a version update. If not, IRRD is up to date and
   no action is needed.
 * Check if there are deltas available to update from the current local
   version to the latest. If not, IRRD was lagging too far behind, and
-  reloads from snapshot.
-* Download and process any relevant delta files.
+  reloads from the snapshot.
+* Otherwise, IRRD can update using the relevant delta files.
+  It will download and process these.
 
 Whenever IRRD reloads from the snapshot, all local RPSL objects and
 journal entries for the source are discarded.