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,134 @@
+Preparing for the Ubuntu 24.04 (Noble) migration
+================================================
+
+In 2025, SecureDrops will need to be upgraded to the newer Ubuntu 24.04 (Noble)
+operating system. This process will 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.
+
+Timeline
+--------
+
+You should ensure all errors are resolved by January 31, 2025, to ensure your SecureDrop
+servers can safely proceed to the next stage of the migration.
+
+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.
+Steps to address each issue are listed below. If you are unsure what to do,
+please :ref:`contact Support <getting_support>`. It is safe to run this command
+multiple times, e.g. if you resolved an issue and want to see that it is fixed.
+
+For example:
+
+.. code:: sh
+
+    $ sudo securedrop-noble-migration-check
+    ssh: group is empty
+    ufw ERROR: ufw is still installed
+    free space: not enough free space, have 88994088, need 4305364600
+    apt: all sources are expected
+    systemd: no failed units
+
+    Some errors were found that will block migration.
+
+    Documentation on how to resolve these errors can be found at:
+    <https://docs.securedrop.org/en/stable/admin/maintenance/noble_migration_prep.html>
+
+    If you are unsure what to do, please contact the SecureDrop
+    support team: <https://docs.securedrop.org/en/stable/getting_support.html>.
+
+In this case the "ufw" check failed.
+
+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 run ``sudo apt clean`` to free up some disk space.
+
+If you have any old sources/submissions that are no longer needed, they should 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|.