The vault service, based on Vaultwarden, serves as a secrets storage application.

[[TOC]]

Tutorial

Welcome email

Hello,

You're receiving this email because you manage some credentials for Tor.

You need to read these instructions carefully -- there are two important actions detailed here that are required for your Vaultwarden account to work fully.

Getting Started

You'll soon receive an email from Vaultwarden <noreply@torproject.org> with the subject, "Join The Tor Project". Please click the link in the email to create your account.

After deciding on a password, you will be sent a verification code to your email address, please obtain that code and provide it to login for the first time.

Critical Steps (must be completed)

Set up Two-Factor Authentication (2FA) immediately after creating your account. Full functionality will not be available without 2FA. Go to Settings->Security->Two-step login to set this up.
Send me your account’s Fingerprint Phrase in a secure way. You can find this under Settings->My Account, there you will find "Your account's fingerprint phrase". Without this step, your account will remain limited.

Once I have received that fingerprint phrase, I will "confirm" your account. Until I have done that, you will not be able to view or add any passwords. Once confirmed, you'll receive another email titled "Invitation to The Tor Project confirmed."

How to use the vault

Vaultwarden is our self-hosted server version of Bitwarden. You can use any Bitwarden client to interact with the vault. Available clients are here: https://bitwarden.com/download/

You can interact with Vaultwarden using https://vault.torproject.org, but the web interface that you have used to setup your account is not the most useful way to use this tool!

The web extension (which you can find at https://bitwarden.com/download) is recommended as the primary method because it is most extensively audited for security and offers ease of use. Other client tools, including desktop applications, are also available. Choose the client that best suits your needs and workflow.

To use one of these clients, simply configure it to use the self-hosted server, and put https://vault.torproject.org as the location.

Adding Credentials

After confirmation, use the web interface:

Navigate to the collection under Collections in the left sidebar.
Click “New” (top right) and select "Item" to add credentials. Credentials added here are accessible by everyone who is part of that collection.

What Credentials to Include:

Any third-party service credentials intended for shared access.
Accounts managed on behalf of The Tor Project.

Do NOT include your OpenPGP private key passphrase.

If unsure, please contact me.

Organizing Credentials

Folders are for organizing credentials hierarchically.
Collections manage different access levels within or across teams.

Create new Folders or Collections using the "New" button.

Additional Documentation

How-to

Check running version

It's possible to query version of Vaultwarven currently running inside the container using the command podman exec vaultwarden /vaultwarden --version.

Disaster recovery

Reference

Installation

This service is installed using the upstream-provided container which runs under Podman.

To set it up, deploy the profile::vaultwarden Puppet profile. This will:

install Podman
deploy an unprivileged user/group pair
manage this user's home directory under /srv/vault.torproject.org
install systemd unit to instantiate and manage the container
install the container configuration in /srv/vault.torproject.org/container-env
create a directory for the container's persistent storage in /srv/vault.torproject.org/data
deploy a cron job to create a database backup

The installation requirements are recorded in the GitLab ticket tpo/tpa/team#41541.

Manual

This procedure documents a manual installation performed in a lab, for testing purposes. It was also done manually because the environment is different than production (Apache vs Nginx, Docker vs Podman).

create system user

addgroup --system vaultwarden
adduser --system vaultwarden

create a Docker compose file, note how the user is numeric below, it needs to match the UID and GID created above:

version: '3'
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: always
    environment:
      DOMAIN: "https://vault.example.com"
      SIGNUPS_ALLOWED: "false"
      ROCKET_ADDRESS: "127.0.0.1"
      ROCKET_PORT: 8086
      IP_HEADER: "X-Forwarded-For"
      SMTP_PORT: 25
      SMTP_HOST: "localhost"
      SMTP_FROM: "vault@example.com"
      HELO_NAME: "vault.example.com"
      SMTP_SECURITY: "off"
    env_file: "admin-token.env"
    volumes:
      - data:/data:Z
    restart: unless-stopped
    network_mode: host
    user: 108:127
volumes:
  data:

create the secrets file:

# generate a strong secret and store it in your password manager
tr -dc '[:alnum:]' < /dev/urandom | head -c  40
docker run --rm -it  vaultwarden/server /vaultwarden hash

copy-paste the ADMIN_TOKEN line in the /etc/docker/admin-token.env file.

start the container, which will fail on a permission issue:
```
docker-compose up
```

fix perms:

chown vaultwarden:vaultwarden /var/lib/docker/volumes/vaultwarden_data/_data

start the container properly
```
docker-compose up
```
setup DNS, webserver and TLS, see their proxy examples
setup backups, upgrades, fail2ban, etc

Assuming you setup the service on the domain vault.example.com, head towards https://vault.example.com/admin to access the admin interface.

Upgrades

Because the cintainer is started with label io.containers.autoupdate=registry and the systemd unit is configured to create new containers on startup (--new switch on the podman generate systemd command) the container will be auto-upgraded daily from the upstream container registry via the podman-auto-update service/timer unit pair (enabled by default on bookworm).

SLA

Design and architecture

Services

The service is set up using a single all-in-one container, pulled from quay.io/vaultwarden/server:latest which listens for HTTP/1.1 connections on port 8080. The container is started/stopped using the container-vaultwarden.service systemd unit.

An nginx instance is installed in front of port 8080 to proxy connections from the standard web ports 80 and 443 and handle HTTPS termination.

Storage

All the Vaultwarden data, including SQlite3 database is stored below /srv/vault.torproject.org/data.

Interfaces

Authentication

Vaultwarden has its own user database.

The instance is administered using a secret ADMIN_TOKEN which allows service admins to login at https://vault.torproject.org/admin

Implementation

Issues

There is no issue tracker specifically for this project, File or search for issues in the team issue tracker with the label ~Foo.

Maintainer

Users

Upstream

Monitoring and metrics

Tests

Logs

The logs for Vaultwarden can be read using journalctl -u container-vaultwarden.service.

Backups

Other documentation

Discussion

Overview

Security and risk assessment

Technical debt and next steps

Proposed Solution

Other alternatives

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search