Admin Guide

Note

SecureDrop wants your feedback! Confused by something in our documentation? Let us know via an issue on GitHub or the community forum.

Responsibilities

The SecureDrop architecture contains multiple machines and hardened servers. While we have automated many of the installation and maintenance tasks, a skilled Linux admin is required to responsibly run the system.

This section outlines the tasks the admin is responsible for in order to ensure that the SecureDrop server continues to be a safe place for sources to talk to journalists.

Maintaining Credentials

The admin should have her own username, passphrase, and two-factor authentication method (via smartphone application or YubiKey). Admins are also responsible for managing user credentials and encouraging best practices. (See Passphrases and Passphrase Best Practices.)

Updating the SecureDrop Servers

The admin should be aware of all SecureDrop updates and take any required manual action if requested in the SecureDrop Release Blog. We recommend subscribing to the SecureDrop RSS Feed to stay apprised of new updates.

Most often, the SecureDrop server will automatically update via apt. However, occasionally you will need to run securedrop-admin install. We will inform you in the release blog when this is the case. If you are onboarded to our SecureDrop Support Portal, we will let you know in advance of major releases if manual intervention will be required.

Updating the Network Firewall

Given all traffic first hits the network firewall as it faces the non-Tor public network, the admin should ensure that critical security patches are applied to the firewall.

Be informed of potential updates to your network firewall. If you’re using the network firewall suggested by FPF, you can subscribe to the Netgate RSS Feed to be alerted when releases occur. If critical security updates need to be applied, you can do so through the firewall’s pfSense WebGUI. Refer to our Keeping pfSense up to Date documentation or the official pfSense Upgrade Docs for further details on how to update the suggested firewall.

Updating the SecureDrop Workstations

The admin should keep all SecureDrop workstations updated with

• Tails updates for each Admin Workstation, Journalist Workstation, and Secure Viewing Station; and
• SecureDrop workstation updates for each Admin Workstation and Journalist Workstation.

You should apply Tails updates to your Tails drives as they are released, as they often contain critical security fixes. Subscribe to the Tails RSS Feed to be alerted of new releases. The online Tails drives, once booted and connected to Tor, will alert you if upgrades are available. Follow the Tails Upgrade Documentation on how to upgrade the drives.

For SecureDrop workstation updates, beginning with SecureDrop 0.7.0, your workstation will automatically check for updates on boot. An update window will pop up when updates are needed, and you should simply follow the prompts in the updater to perform the update.

Note

Note that you will need to have a Tails Administrator password configured to complete the update. If you forget to do so, you will need to reboot to enable it.

Monitoring OSSEC Alerts for Unusual Activity

The admin should decrypt and read all OSSEC alerts. Report any suspicious events to FPF through the SecureDrop Support Portal. See the OSSEC Guide for more information on common OSSEC alerts.

Warning

Do not post logs or alerts to public forums without first carefully examining and redacting any sensitive information.

Note

You can send a test OSSEC alert to verify OSSEC and your email configuration is working properly through the Admin Interface by clicking Send Test OSSEC Alert:

Common Tasks

Adding Users

Now you can add new logins for the journalists at your news organization who will be checking the system for submissions. Make sure the journalist is physically in the same room as you when you do this, as they will have to scan a barcode for their two-factor authentication. Since you’re logged in, this is the screen you should see now:

In the top right corner click the “Admin” link, which should bring you to this page:

Once there, click ‘Add User’ button, which will take you to this page:

Here, you will hand the keyboard over to the journalist so they can create their own username. Once they’re done entering a username for themselves, have them save their pre-generated diceware passphrase to their password manager. Then, you will select whether you would like them to also be an admin (this allows them to add or delete other journalist accounts), and whether they will be using FreeOTP or a YubiKey for two-factor authentication.

Note

We don’t allow the username deleted as we use it to mark the journalists which are deleted from the system.

FreeOTP

If they are using FreeOTP for their two-factor, they can just proceed to the next page:

At this point, the journalist should make sure they have downloaded the FreeOTP app to their smartphone. It can be installed from the Apple Store for an iPhone or from the Google Play store for an Android phone. Once downloaded and opened, the app does not require setup. It should prompt you to scan a barcode. The journalist should use their phone’s camera to scan the barcode on the screen.

If they have difficulty scanning the barcode, they can tap on the icon at the top that shows a plus and the symbol of a key and use their phone’s keyboard to input the two-factor secret (highlighted in yellow) into the Secret input field, without white space.

Inside the FreeOTP app, a new entry for this account will appear on the main screen, with a six digit number that recycles to a new number every thirty seconds. Enter the six digit number under “Verification code” at the bottom of the screen, and hit enter.

If FreeOTP was set up correctly, you will be redirected back to the Admin Interface and will see a confirmation that the two-factor code was verified.

Tip

We recommend using FreeOTP (available for Android and for iOS) to generate two-factor codes because it is Free Software. However, if it does not work for you for any reason, alternatives exist:

• Google Authenticator for Android and iOS (proprietary)
• authenticator for the desktop (Free Software)

YubiKey

If the journalist wishes to use a YubiKey for two-factor authentication, check the box next to “Is using a YubiKey”. You will then need to enter the OATH-HOTP Secret Key that their YubiKey is configured with. For more information, read the YubiKey Setup Guide.

Once you’ve configured the YubiKey and entered the Secret Key, click Add user. On the next page, have the journalist enter a code from their YubiKey by inserting it into the workstation and pressing the button.

If everything was set up correctly, you will be redirected back to the Admin Interface, where you should see a flashed message that says “The two-factor code for user new username was verified successfully.”.

Congratulations! You have successfully set up a journalist on SecureDrop. Make sure the journalist remembers their username and passphrase and always has their two-factor authentication device in their possession when they attempt to log in to SecureDrop.

Passphrases and Two-Factor Resets

Warning

Both of these operations will lock a user out of their SecureDrop account. We recommend having users be physically present when resetting their passphrase or two-factor authentication. If this is not possible, store the passphrase and/or two-factor authentication secret in your own password manager before securely transmitting them to the user in question, and delete them once the user has confirmed they can successfully log in.

While we publish some passphrase best practices, your journalists may occasionally lock themselves out of their accounts. This can happen if, for example, they lose their two-factor device or if they forget the passphrase to their password manager. When this happens, you can reset their account by logging in as an administrator to the Journalist Interface and selecting Admin at the top right. Find their username and select Edit. Next, you can either rotate their passphrase or reset their two-factor authentication. You should make sure the user’s passphrase is saved in a password manager before selecting the “Reset Password” button. To reset a user’s two-factor authentication, choose the button that corresponds to the user’s two-factor authentication method (hardware token, such as a Yubikey, or software-based application, such as FreeOTP).

Off-boarding Users

See our guide to off-boarding users from SecureDrop.

Server Command Line Use

Generally, you should avoid directly SSHing into the servers in favor of using the Admin Interface or securedrop-admin CLI tool. However, in some cases, you may need to SSH in order to troubleshoot and fix a problem that cannot be resolved via these tools.

In this section we cover basic commands you may find useful when you SSH into the Application Server and Monitor Server.

Tip

When you SSH into either SecureDrop server, you will be dropped into a tmux session. tmux is a screen multiplexer - it allows you to tile panes, preserve sessions to keep your session alive if the network connection fails, and more. Check out this tmux tutorial to learn how to use tmux.

Tip

If you want a refresher of the Linux command line, we recommend this resource to cover the fundamentals.

Shutting Down the Servers

sudo shutdown now -h

Rebooting the Servers

sudo reboot

Investigating Logs

Consult our Investigating Logs topic guide for locations of the most relevant log files you may want to examine as part of troubleshooting, and for how to enable error logging for the Source Interface.

Note

You can use the securedrop-admin tool to extract logs to send to Freedom of the Press Foundation for analysis. Run the following command on your Admin Workstation:

cd ~/Persistent/securedrop
./securedrop-admin logs

This command will produce encrypted tarballs containing logs from each server. See the command output for more information.

Immediately Apply a SecureDrop Update

SecureDrop will update and reboot once per day. However, if after a SecureDrop update is announced you wish to fetch the update immediately, you can SSH into each server and run:

sudo cron-apt -i -s

Application Server

Adding Users (CLI)

After the provisioning of the first admin account, we recommend using the Admin Interface web application for adding additional journalists and admins.

However, you can also add users via ./manage.py in /var/www/securedrop/ as described during first install. You can use this command line method if the web application is unavailable.

Restart the Web Server

If you make changes to your Apache configuration, you may want to restart the web server to apply the changes:

sudo service apache2 restart

Cleaning up deleted submissions

When submissions are deleted through the web interface, their database records are deleted and their encrypted files are securely wiped. For large files, secure removal can take some time, and it’s possible, though unlikely, that it can be interrupted, for example by a server reboot. In older versions of SecureDrop this could leave a submission file present without a database record.

As of SecureDrop 1.0.0, automated checks send OSSEC alerts when this situation is detected, recommending you run manage.py list-disconnected-fs-submissions to see the files affected. As with any manage.py usage, you would run the following on the admin workstation:

ssh app
sudo -u www-data bash
cd /var/www/securedrop
./manage.py list-disconnected-fs-submissions

You then have the option of running:

./manage.py delete-disconnected-fs-submissions

to clean them up. As with any potentially destructive operation, it’s recommended that you back the system up before doing so.

There is also the inverse scenario, where a database record could point to a file that no longer exists. This would usually only have happened as a result of disaster recovery, where perhaps the database was recovered from a failed hard drive, but some submissions could not be. The OSSEC alert in this case would recommend running:

./manage.py list-disconnected-db-submissions

To clean up the affected records you would run (again, preferably after a backup):

./manage.py delete-disconnected-db-submissions

Even when submissions are completely removed from the application server, their encrypted files may still exist in backups. We recommend that you delete old backup files with shred, which is available on Tails.

Monitor Server

Restart OSSEC

If you make changes to your OSSEC monitoring configuration, you will want to restart OSSEC via OSSEC’s control script, ossec-control:

sudo /var/ossec/bin/ossec-control restart

Updating the Servers

Sometimes you will want to update the system configuration on the SecureDrop servers. For example, to customize the logo on the source interface, or change the PGP key that OSSEC alerts are encrypted to. You can do this from your Admin Workstation by following the procedure described in this section.

Updating Logo Image

You can update the system logo shown on the web interfaces of your SecureDrop instance via the Admin Interface. We recommend a size of 500px x 450px. Simply click the Update Instance Config button:

And on the instance configuration page, select and upload the PNG image you prefer. You should see a message appear indicating the change was a success:

Updating System Configuration

There are two primary reasons why you may want to update the system configuration:

• to change SecureDrop server configuration options. Example: You want to change the time of day at which the servers are automatically rebooted (default: 4:00 AM).
• to restore a valid configuration state on your servers. Example: Another admin has directly modified the iptables rules during troubleshooting, and you want to reinstate the correct rules.

In both cases, follow these steps:

1. Boot the Admin Workstation and unlock its persistent volume.

2. Open a terminal and type cd ~/Persistent/securedrop.

3. Run git status. If the output includes HEAD detached at followed by the version number displayed in the footer of your Source Interface, you are running the applicable version of the SecureDrop code on your workstation, and can proceed to the next step.

   If not, it is not not safe to proceed. Follow the upgrade instructions associated with the release notes for the most recent release of SecureDrop. Apply all available updates, including for the Tails operating system.

4. Run ./securedrop-admin sdconfig. This will display the current configuration, one line at a time, and allow you to change it. At this point, any changes you make are only saved on this Admin Workstation, to the following file:

   ~/Persistent/securedrop/install_files/ansible-base/group_vars/all/site-specific

5. Run ./securedrop-admin install. This will apply the configuration to your Application and Monitor Server, and enforce the canonical state of the server configuration.

If there is more than one administrator on your team, please also see the following section.

Note

If you see an error running ./securedrop-admin install, and believe it may be an intermittent issue (for example, due to losing network connectivity to the servers), it is safe to run the ./securedrop-admin install command again. If you see the same issue consistently, then you will need to troubleshoot it.

If you see the error message “timeout (62s) waiting for privilege escalation prompt”, try deleting the Ansible control path directory on your Admin Workstation (rm -rf ~/.ansible/cp) to reset the connection to the servers, then re-run the ./securedrop-admin install command from within ~/Persistent/securedrop.

If you encounter other errors, we encourage you to submit a bug report, or to contact us at securedrop@freedom.press (GPG encrypted).

Managing site-specific Updates On Teams With Multiple Admins

Organizations with multiple admins should establish a protocol to communicate any changes one admin makes to the site-specific configuration file on the server.

Currently, when one admin pushes changes in site-specific to the server, the changes will not sync to the local site-specific file on the remaining admin workstations. Without being aware of changes made to site-specific, admins run the risk of pushing old information to the servers. This can affect the receipt of OSSEC alerts, viability of the Submission Key, among other critical components of the SecureDrop environment.

There are multiple ways to avoid pushing out-of-date information to the servers. We recommend admins establish a secure communication pipeline to alert fellow admins of any changes made to site-specific on the server. That clues every admin in on changes in real time, providing all team members with a reminder to manually update all site-specific files.

In addition to secure group communications, admins can learn of updates to the server by monitoring OSSEC alerts. (Please note that while an OSSEC alert can notify you of the occurrence of an update to the server, it may not reveal the content of the change.) Another management option would be SSHing into the server and manually inspecting the configuration to identify any discrepancies.

Configuring Localization for the Source Interface and the Journalist Interface

The Source Interface and Journalist Interface are translated in the following languages:

• Arabic (ar)
• Catalan (ca)
• Czech (cs)
• German (de_DE)
• Greek (el)
• Spanish (es_ES)
• French (fr_FR)
• Hindi (hi)
• Icelandic (is)
• Italian (it_IT)
• Norwegian (nb_NO)
• Dutch (nl)
• Portuguese, Brasil (pt_BR)
• Romanian (ro)
• Russian (ru)
• Slovak (sk)
• Swedish (sv)
• Turkish (tr)
• Chinese, Traditional (zh_Hant)

At any time during and after initial setup, you can choose from a list of supported languages to display using the codes shown in parentheses.

Note

With a Source Interface displayed in French (for example), sources submitting documents are likely to expect a journalist fluent in French to be available to read the documents and follow up in that language.

To add or remove locales from your instance, you’ll need to update your system configuration as outlined above.

When you reach the prompt starting with “Space separated list of additional locales to support”, you will see a list of languages currently supported. Refer to the list above to see which languages correspond to which language codes. For example:

Space separated list of additional locales to support (ru nl pt_BR fr_FR tr it_IT zh_Hant sv hi ar en_US de_DE es_ES nb_NO): nl fr_FR es_ES

You’ll need to list all languages you now want to support, adding or removing languages as needed. Locale changes will be applied after the next reboot.

Frequently Asked Questions

Some initial troubleshooting steps for common scenarios follow. If you continue to have trouble after following these steps, you can contact the SecureDrop team for further assistance.

Generic Troubleshooting Tips

When troubleshooting, ensure you are on the latest version of SecureDrop in your Admin Workstation. This is done by accepting the update when prompted at boot in the GUI that appears.

I can’t SSH into my servers over Tor from my Admin Workstation. What do I do?

At any point after the successful installation of SecureDrop, if you cannot SSH into your Admin Workstation, you should first perform the following troubleshooting steps:

1. Ensure that you are connected to Tor. You can do this by browsing to any site in Tor Browser in your Admin Workstation.

2. Ensure your servers are online. Visit the Admin Interface to check your Application Server is online, and you can trigger a test OSSEC alert to verify your Monitor Server is online.

3. Ensure that SSH aliases and onion service authentication are configured:

   • First, ensure that the correct configuration files are present in ~/Persistent/securedrop/install_files/ansible-base.

     If v2 onion services are configured, you should have 4 files:

     • app-ssh-aths
     • mon-ssh-aths
     • app-journalist-aths
     • app-source-ths

     If v3 onion services are enabled, you should have the following 5 files:

     • app-ssh.auth_private
     • mon-ssh.auth_private
     • app-journalist.auth_private
     • app-sourcev3-ths
     • tor_v3_keys.json

   • Then, from ~/Persistent/securedrop, run ./securedrop-admin tailsconfig. This will ensure your local Tails environment is configured properly.

4. Confirm that your SSH key is available: During the install, you configured SSH public key authentication using ssh-copy-id. Ensure this key is available using ssh-add -L. If you see the output “This agent has no identities.” then you need to add the key via ssh-add prior to SSHing into the servers.

I got a unusual error when running ./securedrop-admin install. What do I do?

If the error message is not informative, try running it again. The Tor connection can be flaky and can cause apparent errors, but there is no negative impact of re-rerunning ./securedrop-admin install more than once. The command will simply check which tasks have been completed, and pick up where it left off. However, if the same issue persists, you will need to investigate further.