Document how to resolve noble pre-migration issues

Give a basic overview on the upcoming noble migration and provide
specifics on what each issue category means and how to resolve each one,
including debugging information to send to support if unsuccessful.

Fixes #610.

docs/admin/maintenance/noble_migration_prep.rst

@@ -0,0 +1,109 @@
+Preparing for the Noble migration
+=================================
+
+In 2025, SecureDrops will need to be upgraded to the newer Ubuntu Noble (24.04)
+operating system. This process will hopefully be more straightforward than in the past
+as there will be semi-automated and fully automated upgrade processes.
+
+At this time, the current focus is on ensuring all SecureDrop servers are in a good state
+to be ready for the migration. SecureDrop will automatically check some conditions, and report
+via an alert in the Journalist Interface and OSSEC alerts if there are issues.
+
+Getting more details
+--------------------
+
+If you see the alert in the Journalist Interface or receive an OSSEC alert, you'll
+need to :doc:`SSH to the Application and Monitor Servers <../installation/test_the_installation>`
+to get more information on what specifically is failing.
+
+Once logged in, run:
+
+.. code:: sh
+
+   sudo securedrop-noble-migration-check
+
+It will display a number of checks and whether they are failing. For example:
+
+TK TK
+
+Steps to address each issue are listed below. If you are unsure what to do,
+please :ref:`contact Support <getting_support>`.
+
+SSH group
+---------
+
+If this fails, it means the migration code in SecureDrop 2.11.0 did not work.
+
+To address it, you can run:
+
+.. code:: sh
+
+   sudo securedrop-migrate-ssh-group.py
+
+If that emits an error, please send it and the output of ``getent group ssh`` to
+:ref:`Support <getting_support>`.
+
+ufw package
+-----------
+
+If this fails, it means the migration code in SecureDrop 2.11.0 did not work.
+
+To address it, you can run:
+
+.. code:: sh
+
+    sudo apt-get purge ufw --yes
+
+If that emits an error, please send it to :ref:`Support <getting_support>`.
+
+Free space
+----------
+
+There needs to be enough free space on the server to both make a backup
+and download the software updates.
+
+You can see how much free space is available on your server by running:
+
+.. code:: sh
+
+    df -h
+
+You should be able to safely delete files in ``/var/cache`` to free up space.
+
+If you have any old sources/submissions that are no longer needed, they can be deleted as well.
+
+APT sources
+-----------
+
+If this fails, it means an unknown source is being used to install software
+on your server.
+
+Please run:
+
+.. code:: sh
+
+    sudo apt-get indextargets
+
+and send the output to :ref:`Support <getting_support>` immediately, so we can diagnose
+the severity.
+
+Failing systemd units
+---------------------
+
+If this fails, it means a process monitored by systemd is failing.
+
+You can see which process is failing by running:
+
+.. code:: sh
+
+    sudo systemctl list-units
+
+Once you know which unit is failing, run:
+
+.. code:: sh
+
+    sudo systemctl status <name>
+
+to get more information about why it failed.
+
+If you are unsure or need help debugging, please :ref:`contact Support <getting_support>`.

docs/index.rst

@@ -47,7 +47,7 @@ Get Started
    getting_support
    training_schedule
    passphrase_best_practices
-   
+
 .. toctree::
    :caption: Source Guide
    :name: sourceguidetoc
@@ -144,6 +144,7 @@ Get Started
    admin/maintenance/rebuild_admin
    admin/maintenance/update_bios
    admin/maintenance/decommission
+   admin/maintenance/noble_migration_prep
 
 .. toctree::
    :caption: Admin Guide: Upgrades
@@ -165,10 +166,10 @@ SecureDrop is an open source project. If you would like to contribute
 to SecureDrop, please see our
 `developer documentation <https://developers.securedrop.org/>`_.
 
-Two versions of this documentation are available, and can be selected in the 
+Two versions of this documentation are available, and can be selected in the
 lower left corner using the version dropdown menu:
 
-- ``latest`` - built from the ``develop`` branch of the SecureDrop 
+- ``latest`` - built from the ``develop`` branch of the SecureDrop
   repository, containing updates that have been tested but not yet released.
 - ``stable`` - built from the ``stable`` branch of the SecureDrop repository,
   and up to date with the most recent release, |version|.