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.
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 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¶
Do not post logs or alerts to public forums without first carefully examining and redacting any sensitive information.
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:
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.
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.
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¶
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).
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.
When you SSH into either SecureDrop server, you will be dropped into a
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
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¶
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.
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
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
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
list-disconnected-fs-submissions to see the files affected. As with
manage.py usage, you would run the following on the admin
ssh app sudo -u www-data bash cd /var/www/securedrop ./manage.py list-disconnected-fs-submissions
You then have the option of running:
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:
To clean up the affected records you would run (again, preferably after a backup):
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
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:
Boot the Admin Workstation and unlock its persistent volume.
Open a terminal and type
git status. If the output includes
HEAD detached atfollowed 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.
./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:
./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.
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
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
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 (
- Catalan (
- Czech (
- German (
- Greek (
- Spanish (
- French (
- Hindi (
- Icelandic (
- Italian (
- Norwegian (
- Dutch (
- Portuguese, Brasil (
- Romanian (
- Russian (
- Slovak (
- Swedish (
- Turkish (
- Chinese, Traditional (
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.
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:
Ensure that you are connected to Tor. You can do this by browsing to any site in Tor Browser in your Admin Workstation.
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.
Ensure that SSH aliases and onion service authentication are configured:
First, ensure that the correct configuration files are present in
If v2 onion services are configured, you should have 4 files:
If v3 onion services are enabled, you should have the following 5 files:
./securedrop-admin tailsconfig. This will ensure your local Tails environment is configured properly.
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-addprior 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