Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

update installation instructions for Ubuntu Noble itself #638

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+30 −196
Open

update installation instructions for Ubuntu Noble itself #638

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ca63460
link to platform-specific Ubuntu tutorials for creating bootable media
cfm Feb 26, 2025
2620a88
update installation instructions for Ubuntu Noble
cfm Feb 26, 2025
649de4b
update download and verification instructions for Ubuntu Noble
cfm Feb 26, 2025
86acd0f
update backup/restore instructions for Ubuntu Noble
cfm Feb 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 17 additions & 12 deletions docs/admin/installation/create_usb_boot_drives.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,7 @@ Ubuntu Introduction
exactly as there are some "gotchas" that may cause your SecureDrop setup to break.

The SecureDrop *Application Server* and *Monitor Server* run **Ubuntu Server
20.04.6 LTS (Focal Fossa)**. To install Ubuntu on the servers, you must first
24.04.2 LTS (Noble Numbat)**. To install Ubuntu on the servers, you must first
download and verify the Ubuntu installation media.

.. _download_ubuntu:
Expand All @@ -136,7 +136,7 @@ Download the Ubuntu Installation Media
The installation media and the files required to verify it are available on the
`Ubuntu Releases page`_. You will need to download the following files:

* `ubuntu-20.04.6-live-server-amd64.iso`_
* `ubuntu-24.04.2-live-server-amd64.iso`_
* `SHA256SUMS`_
* `SHA256SUMS.gpg`_

Expand All @@ -145,12 +145,12 @@ Alternatively, you can use the command line:
.. code:: sh

cd ~/Downloads
curl -OOO https://releases.ubuntu.com/20.04.6/{ubuntu-20.04.6-live-server-amd64.iso,SHA256SUMS{,.gpg}}
curl -OOO https://releases.ubuntu.com/24.04.2/{ubuntu-24.04.2-live-server-amd64.iso,SHA256SUMS{,.gpg}}

.. _Ubuntu Releases page: https://releases.ubuntu.com/
.. _ubuntu-20.04.6-live-server-amd64.iso: https://releases.ubuntu.com/20.04/ubuntu-20.04.6-live-server-amd64.iso
.. _SHA256SUMS: https://releases.ubuntu.com/20.04/SHA256SUMS
.. _SHA256SUMS.gpg: https://releases.ubuntu.com/20.04/SHA256SUMS.gpg
.. _ubuntu-24.04.2-live-server-amd64.iso: https://releases.ubuntu.com/24.04/ubuntu-24.04.2-live-server-amd64.iso
.. _SHA256SUMS: https://releases.ubuntu.com/24.04/SHA256SUMS
.. _SHA256SUMS.gpg: https://releases.ubuntu.com/24.04/SHA256SUMS.gpg

Verify the Ubuntu Installation Media
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -196,12 +196,12 @@ key") means that you are not ready to proceed. ::

The next and final step is to verify the Ubuntu image. ::

sha256sum -c <(grep ubuntu-20.04.6-live-server-amd64.iso SHA256SUMS)
sha256sum -c <(grep ubuntu-24.04.2-live-server-amd64.iso SHA256SUMS)

If the final verification step is successful, you should see the
following output in your terminal. ::

ubuntu-20.04.6-live-server-amd64.iso: OK
ubuntu-24.04.2-live-server-amd64.iso: OK

.. caution:: If you do not see the line above it is not safe to proceed with the
installation. If this happens, please contact us at
Expand All @@ -212,10 +212,15 @@ Create the Ubuntu Installation Media
The `Ubuntu website <https://ubuntu.com/>`__ has detailed instructions on how to
to create a bootable Ubuntu Server USB drive.

Follow the instructions at the link below, then return to this page:

- `Create a bootable Ubuntu USB drive on Ubuntu,
Windows, or Mac <https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview>`__
Follow the instructions at the link below for your operating system, then return
to this page:

- `Create a bootable Ubuntu USB drive on Mac
<https://ubuntu.com/tutorials/create-a-usb-stick-on-macos#1-overview>`__
- `Create a bootable Ubuntu USB drive on Windows
<https://ubuntu.com/tutorials/create-a-usb-stick-on-windows#1-overview>`__
- `Create a bootable Ubuntu USB drive on Linux
<https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu#1-overview>`__

.. |Persistent Storage App| image:: ../../images/tails_5x/persistent_storage_app.png
:alt: The Persistent Storage app in Tails 5.8 and later, displaying settings for which persistent storage features should be enabled
19 changes: 10 additions & 9 deletions docs/admin/installation/servers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,11 +61,11 @@ display a message on boot that shows which key should be pressed to
enter the boot menu. Once you've entered the boot menu, select the
installation media (USB or CD) and press Enter to boot it.

On newer hardware, such as the NUC12s, you may need to use a newer Linux
kernel than the one that ships by default in **Ubuntu Server 20.04.6** in
order to have more up-to-date hardware drivers. To use a newer Linux kernel,
select **Boot and Install with the HWE Kernel** in the initial OS boot menu
that appears prior to booting the Ubuntu image.
On newer hardware, such as the NUC12s, you may need to use a newer Linux kernel
than the one that ships by default in **Ubuntu Server 24.04.2** in order to have
more up-to-date hardware drivers. To use a newer Linux kernel, select **Ubuntu
Server with the HWE kernel** in the initial OS boot menu that appears prior to
booting the Ubuntu image.

After booting the Ubuntu image, select **Install Ubuntu Server**.

Expand Down Expand Up @@ -185,10 +185,11 @@ Select **Done** and press **Enter** to proceed.
only be allowed to enter one password, so it must be identical on
both servers.

Ignore Enable Ubuntu Advantage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On the **Enable Ubuntu Advantage** screen, choose **Done** to proceed without entering
a token. The SecureDrop servers should not be registered with Ubuntu Advantage.
Decline upgrade to Ubuntu Pro
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The SecureDrop servers should not be registered with Ubuntu Advantage. On the
**Upgrade to Ubuntu Pro** screen, make sure **Skip for now** is selected, then
choose **Continue**.

Set up SSH access
~~~~~~~~~~~~~~~~~
Expand Down
178 changes: 3 additions & 175 deletions docs/admin/maintenance/backup_and_restore.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,12 +147,6 @@ This command attempts to restore submissions, source and journalist accounts,
and configuration details for the onion services used by the web interfaces and
SSH (if configured).

.. note:: You cannot restore v2 onion service configurations to a v3-only server
(this includes any SecureDrop installation based on Ubuntu 20.04). If a
restore operation would leave you without a valid onion service configuration,
the restore script will fail with an error. In this case, you can still perform
a data-only restore. See :ref:`Data-only Restores <additional_restore_info>` for more information.

.. _migrating:

Migrating Using a Backup
Expand All @@ -164,26 +158,11 @@ Moving a SecureDrop instance to new hardware involves:
- Installing SecureDrop on new hardware;
- Restoring the backup to the new instance and repairing credentials.

SecureDrop now supports only v3 onion services, so the final configuration will
only include v3 onion services regardless of the backup state.

.. note:: If you need to restore from a backup from an instance configured to
use SSH-over-LAN onto an SSH-over-Tor instance, you must either first update
the target instance to use SSH-over-LAN or perform a data-only backup.
See :ref:`Data-only Restores <additional_restore_info>` for more information.


The restore process differs based on the onion services that were configured on
the old instance and preserved in the backup:

- :ref:`Migrating using a v2+v3 or v3-only backup <migrate_v3>`
- :ref:`Migrating using a v2-only backup <migrate_v2>`

.. _migrate_v3:

Migrating Using a V2+V3 or V3-Only Backup
'''''''''''''''''''''''''''''''''''''''''

.. note:: The instructions below assume that you are using the same *Admin Workstation*
that was used to manage your old instance. If you are using a new *Admin
Workstation* you will need to copy the directory ``~amnesia/Persistent/securedrop``
Expand Down Expand Up @@ -296,15 +275,15 @@ Migrating Using a V2+V3 or V3-Only Backup
network firewall, and
:ref:`configure the Admin Workstation's IP address <assign_static_ip_to_workstation>`.

#. Install Ubuntu 20.04 on the *Application* and *Monitor Servers*, following
#. Install Ubuntu 24.04 on the *Application* and *Monitor Servers*, following
the :doc:`server setup instructions<../installation/servers>` to install
with the correct settings, test connectivity, and set up SSH keys to allow
for *Admin Workstation* access.

.. note::

You may need to wait approximately 10-15 minutes after installing
Ubuntu 20.04 for the servers to become reachable via SSH.
Ubuntu 24.04 for the servers to become reachable via SSH.

#. Reinstall SecureDrop on the servers, following the :doc:`installation
instructions <../installation/install>`. During the configuration stage
Expand Down Expand Up @@ -346,7 +325,7 @@ Migrating Using a V2+V3 or V3-Only Backup
.. _repair_admin_usbs:

Repair Additional Admin Workstations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
''''''''''''''''''''''''''''''''''''

If you have additional *Admin Workstation* USBs, they will no longer have
valid SSH credentials and will need to be repaired. In these steps, the "primary
Expand Down Expand Up @@ -419,157 +398,6 @@ process.
.. _contact Support: https://support-docs.securedrop.org/
.. _an administration password: https://tails.net/doc/first_steps/welcome_screen/administration_password

.. _migrate_v2:

Migrating Using a V2-Only Backup
''''''''''''''''''''''''''''''''

V2 onion services are no longer supported by SecureDrop, so v2 *Source* and
*Journalist Interface* addresses will be replaced by v3 addresses when you perform a
migration using a v2-only backup. However, it is possible to migrate submissions,
source accounts, and journalist accounts. To do so, follow the steps below:

.. note:: The instructions below assume that you are using the same
*Admin Workstation*
that was used to manage your old instance. If you are using a new
*Admin Workstation* you will need to copy the directory
``~amnesia/Persistent/securedrop``
from the old workstation to the new workstation (using a *Transfer Device*)
before proceeding.

#. If you have not already done so,
:ref:`back up the existing installation <backing_up>`.
The instructions below assume that the backup has been created and
renamed ``sd-backup-old.tar.gz``.

#. Move the existing *Admin Workstation* SecureDrop code out of the way, by
opening a Terminal via **Applications ▸ System Tools ▸ Terminal** and
running the command:

.. code:: sh

mv ~/Persistent/securedrop ~/Persistent/sd.bak

#. Move the existing *Admin Workstation* SSH configuration out of the way via
the Terminal, using the commands:

.. code:: sh

ssh-add -D
find ~/.ssh/ -type f -exec mv {} {}.bak \;

#. Reinstall SecureDrop on the *Admin Workstation* using the following Terminal
commands:

.. code:: sh

cd ~/Persistent
git clone https://github.com/freedomofpress/securedrop

#. Verify that the current release tag was signed with the release signing key:

.. code:: sh

cd ~/Persistent/securedrop/
git fetch --tags
git tag -v 2.11.1

The output should include the following two lines:

.. code:: sh

gpg: using RSA key 2359E6538C0613E652955E6C188EDD3B7B22E6A3
gpg: Good signature from "SecureDrop Release Signing Key <[email protected]>" [unknown]

.. important::
If you do not see the message above, signature verification has failed
and you should **not** proceed with the installation. If this happens,
please contact us at [email protected].

Verify that each character of the fingerprint matches what is on the
screen of your workstation. If it does, you can check out the new release:

.. code:: sh

git checkout 2.11.1


.. important::
If you see the warning ``refname '2.11.1' is ambiguous`` in the
output, we recommend that you contact us immediately at
[email protected] (`GPG encrypted <https://securedrop.org/sites/default/files/fpf-email.asc>`__).

#. Copy the old instance's configuration files and backup from ``~/Persistent/sd.bak`` into ``~/Persistent/securedrop`` using the following Terminal commands:

.. code:: sh

cd ~/Persistent/securedrop
export SD_OLD=~/Persistent/sd.bak/install_files/ansible-base
export SD_NEW=~/Persistent/securedrop/install_files/ansible-base
cp $SD_OLD/group_vars/all/site-specific $SD_NEW/group_vars/all/
cp $SD_OLD/sd-backup-old.tar.gz $SD_NEW/

You will also need to copy the old instance's *Submission Public Key*,
*OSSEC Alert Public Key*, and, if configured, the *Journalist Alert Public Key*.
Assuming that these are named ``SecureDrop.asc``, ``ossec.asc``, and
``journalist.asc`` respectively, run the following commands:

.. code:: sh

cp $SD_OLD/SecureDrop.asc $SD_NEW/
cp $SD_OLD/ossec.asc $SD_NEW/

#. Ensure your *Admin Workstation* is connected to a LAN port on your
network firewall, and
:ref:`configure the Admin Workstation's IP address <assign_static_ip_to_workstation>`.

#. Install Ubuntu 20.04 on the *Application* and *Monitor Servers*, following
the :doc:`server setup instructions<../installation/servers>` to install with the correct
settings, test connectivity, and set up SSH keys to allow for
*Admin Workstation* access.

.. note::

You may need to wait approximately 10-15 minutes after installing
Ubuntu 20.04 for the servers to become reachable via SSH.

#. Reinstall SecureDrop on the servers, following the :doc:`installation
instructions <../installation/install>`. During the configuration stage
(``./securedrop-admin sdconfig``), the values will be prepopulated based on
the old instance's configuration. Press **Enter** to accept each value.

.. note::

If your old instance served the *Source Interface* over HTTPS,
you will need to set up your new instance using HTTP instead, and update
it to use HTTPS after the initial migration. The web interface addresses
change as part of the process, and so your certificate is no longer valid.

Proceed through the installation by running
``./securedrop-admin install`` then ``./securedrop-admin tailsconfig``.
If SSH-over-Tor is configured, run
``ssh app uptime`` and ``ssh mon uptime`` in the Terminal to verify SSH
connectivity and add the new onion URLs to your ``known_hosts`` file.

#. Restore from the old instance's backup (e.g. ``sd-backup-old.tar.gz``) using
the Terminal command:

.. code:: sh

./securedrop-admin restore --preserve-tor-config sd-backup-old.tar.gz

The new instance's onion service addresses will be unchanged, but the
old instance's data and accounts will now be available.

#. As part of this process, your .onion URLs have changed, and any old
*Journalist* and *Admin Workstations* will no longer work. To create
additional *Journalist Workstations*, see our
:doc:`onboarding documentation <../deployment/onboarding_journalists>`.

#. If you have migrated to new hardware, ensure your old servers have been
decommissioned and/or destroyed by following the relevant sections of
:doc:`our decommissioning documentation <decommission>`.

.. _additional_restore_info:

Additional Information
Expand Down