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|.