From 7582d61e664e5ca1702fb9a800e8f4167c12fd78 Mon Sep 17 00:00:00 2001 From: Kunal Mehta Date: Fri, 22 Nov 2024 16:14:05 -0800 Subject: [PATCH] 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. --- .../maintenance/noble_migration_prep.rst | 128 ++++++++++++++++++ docs/index.rst | 7 +- 2 files changed, 132 insertions(+), 3 deletions(-) create mode 100644 docs/admin/maintenance/noble_migration_prep.rst diff --git a/docs/admin/maintenance/noble_migration_prep.rst b/docs/admin/maintenance/noble_migration_prep.rst new file mode 100644 index 000000000..5b65bac60 --- /dev/null +++ b/docs/admin/maintenance/noble_migration_prep.rst @@ -0,0 +1,128 @@ +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 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. +Steps to address each issue are listed below. If you are unsure what to do, +please :ref:`contact 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: + + + If you are unsure what to do, please contact the SecureDrop + support team: . + +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 `. + +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 `. + +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 ` 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 + +to get more information about why it failed. + +If you are unsure or need help debugging, please :ref:`contact Support `. diff --git a/docs/index.rst b/docs/index.rst index 588bded28..ba6e28ff1 100644 --- a/docs/index.rst +++ b/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 `_. -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|.