Changes

Page history
Update vault with welcome email authored by micah's avatar micah
Hide whitespace changes
Inline Side-by-side
service/vault.md
View page @ 3e86d9a2
The vault service, based on [Vaultwarden][], serves as a secrets storage The vault service, based on [Vaultwarden][], serves as a secrets storage
application. application.
[Vaultwarden]: https://github.com/dani-garcia/vaultwarden [Vaultwarden]: https://github.com/dani-garcia/vaultwarden
[[_TOC_]] [[_TOC_]]
<!-- note: this template was designed based on multiple sources: --> <!-- note: this template was designed based on multiple sources: -->
<!-- https://diataxis.fr/ --> <!-- https://diataxis.fr/ -->
<!-- http://opsreportcard.com/section/9--> <!-- http://opsreportcard.com/section/9-->
<!-- http://opsreportcard.com/section/11 --> <!-- http://opsreportcard.com/section/11 -->
<!-- comments like this one should be removed on instantiation --> <!-- comments like this one should be removed on instantiation -->
# Tutorial # Tutorial
<!-- simple, brainless step-by-step instructions requiring little or --> ## Welcome email
<!-- no technical background -->
Hello,
# How-to
You need to read these instructions carefully—there are two important actions required for your Vaultwarden account to work fully.
<!-- more in-depth procedure that may require interpretation -->
---
## Pager playbook
You're receiving this email because you manage credentials for Tor's third-party services. We're introducing **Vaultwarden**, a self-hosted password manager, to securely share team and organizational credentials.
### Check running version
### Getting Started
It's possible to query version of Vaultwarven currently running inside the
container using the command `podman exec vaultwarden /vaultwarden --version`. You'll soon receive two emails from Vaultwarden `<noreply@torproject.org>`:
<!-- information about common errors from the monitoring system and --> - An invitation to create an account.
<!-- how to deal with them. this should be easy to follow: think of --> - An invitation to join your team's "Organization."
<!-- your future self, in a stressful situation, tired and hungry. -->
You **only need to click the link in the second email** (team invitation). This link will let you both create your account and join your team.
## Disaster recovery
### Critical Steps (must be completed)
<!-- what to do if all goes to hell. e.g. restore from backups? -->
<!-- rebuild from scratch? not necessarily those procedures (e.g. see --> 1. **Set up Two-Factor Authentication (2FA)** immediately after creating your account. Full functionality will not be available without 2FA.
<!-- "Installation" below but some pointers. --> 2. **Send me your account’s Fingerprint Phrase securely** (found under your account settings). Without this step, your account will remain limited, and you should not add credentials yet.
# Reference Once confirmed, you'll receive another email titled **"Invitation to The Tor Project confirmed."**
<!-- this section is a more in-depth review of how this service works, --> ### Adding Credentials
<!-- how it's setup. day-to-day operation should be covered in -->
<!-- tutorial or how-to, this is more in-depth --> After confirmation, use the web interface:
<!-- a good guide to "audit" an existing project's design: --> - Navigate to the `Tails Team` collection under **Collections** in the left sidebar.
<!-- https://bluesock.org/~willkg/blog/dev/auditing_projects.html --> - Click **“New”** (top right) and select **"Item"** to add credentials. Credentials added here are accessible by the team.
<!-- the following sections are partially based on that -->
**What Credentials to Include:**
## Installation
- Any third-party service credentials intended for shared access.
This service is installed using the upstream-provided container which runs under - Accounts managed on behalf of The Tor Project.
[Podman][].
**Do NOT include your OpenPGP private key passphrase.**
To set it up, deploy the `profile::vaultwarden` Puppet profile. This will:
If unsure, please contact me.
- install Podman
- deploy an unprivileged user/group pair ### Organizing Credentials
- manage this user's home directory under `/srv/vault.torproject.org`
- install systemd unit to instantiate and manage the container - **Folders** are for organizing credentials hierarchically.
- install the container configuration in - **Collections** manage different access levels within or across teams.
`/srv/vault.torproject.org/container-env`
- create a directory for the container's persistent storage in Create new Folders or Collections using the **"New"** button.
`/srv/vault.torproject.org/data`
- deploy a cron job to create a database backup ### Client Tools
The installation requirements are recorded in the GitLab ticket You can also interact with Vaultwarden using various client tools. The web extension 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.
[tpo/tpa/team#41541](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41541).
### Additional Documentation
[Podman]: https://podman.io/
- [Managing Items](https://bitwarden.com/help/managing-items/)
### Manual - [Folders](https://bitwarden.com/help/folders/)
- [Collections](https://bitwarden.com/help/about-collections/)
This procedure documents a manual installation performed in a lab, for
testing purposes. It was also done manually because the environment is # How-to
different than production (Apache vs Nginx, Docker vs Podman).
<!-- more in-depth procedure that may require interpretation -->
1. create system user
## Pager playbook
addgroup --system vaultwarden
adduser --system vaultwarden ### Check running version
2. create a Docker compose file, note how the `user` is numeric It's possible to query version of Vaultwarven currently running inside the
below, it needs to match the UID and GID created above: container using the command `podman exec vaultwarden /vaultwarden --version`.
``` <!-- information about common errors from the monitoring system and -->
version: '3' <!-- how to deal with them. this should be easy to follow: think of -->
services: <!-- your future self, in a stressful situation, tired and hungry. -->
vaultwarden:
image: vaultwarden/server:latest ## Disaster recovery
container_name: vaultwarden
restart: always <!-- what to do if all goes to hell. e.g. restore from backups? -->
environment: <!-- rebuild from scratch? not necessarily those procedures (e.g. see -->
DOMAIN: "https://vault.example.com" <!-- "Installation" below but some pointers. -->
SIGNUPS_ALLOWED: "false"
ROCKET_ADDRESS: "127.0.0.1" # Reference
ROCKET_PORT: 8086
IP_HEADER: "X-Forwarded-For" <!-- this section is a more in-depth review of how this service works, -->
SMTP_PORT: 25 <!-- how it's setup. day-to-day operation should be covered in -->
SMTP_HOST: "localhost" <!-- tutorial or how-to, this is more in-depth -->
SMTP_FROM: "vault@example.com"
HELO_NAME: "vault.example.com" <!-- a good guide to "audit" an existing project's design: -->
SMTP_SECURITY: "off" <!-- https://bluesock.org/~willkg/blog/dev/auditing_projects.html -->
env_file: "admin-token.env" <!-- the following sections are partially based on that -->
volumes:
- data:/data:Z ## Installation
restart: unless-stopped
network_mode: host This service is installed using the upstream-provided container which runs under
user: 108:127 [Podman][].
volumes:
data: To set it up, deploy the `profile::vaultwarden` Puppet profile. This will:
```
- install Podman
3. create the secrets file: - deploy an unprivileged user/group pair
- manage this user's home directory under `/srv/vault.torproject.org`
# generate a strong secret and store it in your password manager - install systemd unit to instantiate and manage the container
tr -dc '[:alnum:]' < /dev/urandom | head -c 40 - install the container configuration in
docker run --rm -it vaultwarden/server /vaultwarden hash `/srv/vault.torproject.org/container-env`
- create a directory for the container's persistent storage in
copy-paste the `ADMIN_TOKEN` line in the `/etc/docker/admin-token.env` file. `/srv/vault.torproject.org/data`
- deploy a cron job to create a database backup
4. start the container, which will fail on a permission issue:
The installation requirements are recorded in the GitLab ticket
docker-compose up [tpo/tpa/team#41541](https://gitlab.torproject.org/tpo/tpa/team/-/issues/41541).
5. fix perms: [Podman]: https://podman.io/
chown vaultwarden:vaultwarden /var/lib/docker/volumes/vaultwarden_data/_data ### Manual
6. start the container properly This procedure documents a manual installation performed in a lab, for
testing purposes. It was also done manually because the environment is
docker-compose up different than production (Apache vs Nginx, Docker vs Podman).
7. setup DNS, webserver and TLS, see their [proxy examples](https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples) 1. create system user
8. setup backups, upgrades, fail2ban, etc addgroup --system vaultwarden
adduser --system vaultwarden
Assuming you setup the service on the domain `vault.example.com`, head
towards `https://vault.example.com/admin` to access the admin 2. create a Docker compose file, note how the `user` is numeric
interface. below, it needs to match the UID and GID created above:
## Upgrades ```
version: '3'
Because the cintainer is started with label `io.containers.autoupdate=registry` services:
and the systemd unit is configured to create new containers on startup (`--new` vaultwarden:
switch on the `podman generate systemd` command) the container will be image: vaultwarden/server:latest
auto-upgraded daily from the upstream container registry via the container_name: vaultwarden
`podman-auto-update` service/timer unit pair (enabled by default on bookworm). restart: always
environment:
## SLA DOMAIN: "https://vault.example.com"
SIGNUPS_ALLOWED: "false"
<!-- this describes an acceptable level of service for this service --> ROCKET_ADDRESS: "127.0.0.1"
ROCKET_PORT: 8086
## Design and architecture IP_HEADER: "X-Forwarded-For"
SMTP_PORT: 25
<!-- how this is built --> SMTP_HOST: "localhost"
<!-- should reuse and expand on the "proposed solution" discussed in --> SMTP_FROM: "vault@example.com"
<!-- a previous RFC or the Discussion section below. it's a --> HELO_NAME: "vault.example.com"
<!-- "as-built" documented, whereas the "Proposed solution" is an --> SMTP_SECURITY: "off"
<!-- "architectural" document, which the final result might differ --> env_file: "admin-token.env"
<!-- from, sometimes significantly --> volumes:
- data:/data:Z
## Services restart: unless-stopped
network_mode: host
The service is set up using a single all-in-one container, pulled from user: 108:127
`quay.io/vaultwarden/server:latest` which listens for HTTP/1.1 connections on volumes:
port 8080. The container is started/stopped using the data:
`container-vaultwarden.service` systemd unit. ```
An nginx instance is installed in front of port 8080 to proxy connections from 3. create the secrets file:
the standard web ports 80 and 443 and handle HTTPS termination.
# generate a strong secret and store it in your password manager
## Storage tr -dc '[:alnum:]' < /dev/urandom | head -c 40
docker run --rm -it vaultwarden/server /vaultwarden hash
All the Vaultwarden data, including SQlite3 database is stored below
`/srv/vault.torproject.org/data`. copy-paste the `ADMIN_TOKEN` line in the `/etc/docker/admin-token.env` file.
## Interfaces 4. start the container, which will fail on a permission issue:
<!-- e.g. web APIs, commandline clients, etc --> docker-compose up
## Authentication 5. fix perms:
Vaultwarden has its own user database. chown vaultwarden:vaultwarden /var/lib/docker/volumes/vaultwarden_data/_data
The instance is administered using a secret `ADMIN_TOKEN` which allows service 6. start the container properly
admins to login at https://vault.torproject.org/admin
docker-compose up
## Implementation
7. setup DNS, webserver and TLS, see their [proxy examples](https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples)
<!-- programming languages, frameworks, versions, license -->
8. setup backups, upgrades, fail2ban, etc
## Related services
Assuming you setup the service on the domain `vault.example.com`, head
<!-- dependent services (e.g. authenticates against LDAP, or requires --> towards `https://vault.example.com/admin` to access the admin
<!-- git pushes) --> interface.
## Issues ## Upgrades
<!-- such projects are never over. add a pointer to well-known issues --> Because the cintainer is started with label `io.containers.autoupdate=registry`
<!-- and show how to report problems. usually a link to the --> and the systemd unit is configured to create new containers on startup (`--new`
<!-- issue tracker. consider creating a new Label to regroup the --> switch on the `podman generate systemd` command) the container will be
<!-- issues if using the general tracker. see also TPA-RFC-19. --> auto-upgraded daily from the upstream container registry via the
`podman-auto-update` service/timer unit pair (enabled by default on bookworm).
There is no issue tracker specifically for this project, [File][] or
[search][] for issues in the [team issue tracker][search] with the ## SLA
label ~Foo.
<!-- this describes an acceptable level of service for this service -->
[File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
[search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues?label_name%5B%5D=Foo ## Design and architecture
## Maintainer <!-- how this is built -->
<!-- should reuse and expand on the "proposed solution" discussed in -->
<!-- document who deployed and operates this service, the team and --> <!-- a previous RFC or the Discussion section below. it's a -->
<!-- ideally the person inside that team --> <!-- "as-built" documented, whereas the "Proposed solution" is an -->
<!-- "architectural" document, which the final result might differ -->
## Users <!-- from, sometimes significantly -->
<!-- who the main users are, how they use the service. possibly reuse --> ## Services
<!-- the Personas section in the RFC, if available. -->
The service is set up using a single all-in-one container, pulled from
## Upstream `quay.io/vaultwarden/server:latest` which listens for HTTP/1.1 connections on
port 8080. The container is started/stopped using the
<!-- who the upstreams are, if they are still active, --> `container-vaultwarden.service` systemd unit.
<!-- collaborative, how do we keep up to date, support channels, see -->
<!-- also the "Issues" section above --> 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.
## Monitoring and metrics
## Storage
<!-- describe how this service is monitored, how security issues and -->
<!-- upgrades are tracked, see also "Upgrades" above. --> All the Vaultwarden data, including SQlite3 database is stored below
`/srv/vault.torproject.org/data`.
## Tests
## Interfaces
<!-- how the service can be tested, for example after major changes -->
<!-- like IP address changes or upgrades. describe CI, test suites, linting --> <!-- e.g. web APIs, commandline clients, etc -->
## Logs ## Authentication
The logs for Vaultwarden can be read using Vaultwarden has its own user database.
`journalctl -u container-vaultwarden.service`.
The instance is administered using a secret `ADMIN_TOKEN` which allows service
## Backups admins to login at https://vault.torproject.org/admin
<!-- does this service need anything special in terms of backups? --> ## Implementation
<!-- e.g. locking a database? special recovery procedures? -->
<!-- programming languages, frameworks, versions, license -->
## Other documentation
## Related services
<!-- references to upstream documentation, if relevant -->
<!-- dependent services (e.g. authenticates against LDAP, or requires -->
# Discussion <!-- git pushes) -->
<!-- the "discussion" section is where you put any longer conversation --> ## Issues
<!-- about the project that you will not need in a casual -->
<!-- review. history of the project, why it was done the way it was --> <!-- such projects are never over. add a pointer to well-known issues -->
<!-- (as opposed to how), alternatives, and other proposals are --> <!-- and show how to report problems. usually a link to the -->
<!-- relevant here. --> <!-- issue tracker. consider creating a new Label to regroup the -->
<!-- issues if using the general tracker. see also TPA-RFC-19. -->
<!-- this at least partly overlaps with the TPA-RFC process (see -->
<!-- policy.md), but in general should defer to proposals when --> There is no issue tracker specifically for this project, [File][] or
<!-- available --> [search][] for issues in the [team issue tracker][search] with the
label ~Foo.
## Overview
[File]: https://gitlab.torproject.org/tpo/tpa/team/-/issues/new
<!-- describe the overall project. should include a link to a ticket --> [search]: https://gitlab.torproject.org/tpo/tpa/team/-/issues?label_name%5B%5D=Foo
<!-- that has a launch checklist -->
## Maintainer
<!-- if this is an old project being documented, summarize the known -->
<!-- issues with the project. --> <!-- document who deployed and operates this service, the team and -->
<!-- ideally the person inside that team -->
## Security and risk assessment
## Users
<!--
<!-- who the main users are, how they use the service. possibly reuse -->
5. When was the last security review done on the project? What was <!-- the Personas section in the RFC, if available. -->
the outcome? Are there any security issues currently? Should it
have another security review? ## Upstream
6. When was the last risk assessment done? Something that would cover <!-- who the upstreams are, if they are still active, -->
risks from the data stored, the access required, etc. <!-- collaborative, how do we keep up to date, support channels, see -->
<!-- also the "Issues" section above -->
-->
## Monitoring and metrics
## Technical debt and next steps
<!-- describe how this service is monitored, how security issues and -->
<!-- <!-- upgrades are tracked, see also "Upgrades" above. -->
7. Are there any in-progress projects? Technical debt cleanup? ## Tests
Migrations? What state are they in? What's the urgency? What's the
next steps? <!-- how the service can be tested, for example after major changes -->
<!-- like IP address changes or upgrades. describe CI, test suites, linting -->
8. What urgent things need to be done on this project?
## Logs
-->
The logs for Vaultwarden can be read using
## Proposed Solution `journalctl -u container-vaultwarden.service`.
<!-- Link to RFC --> ## Backups
## Other alternatives <!-- does this service need anything special in terms of backups? -->
<!-- e.g. locking a database? special recovery procedures? -->
<!-- include benchmarks and procedure if relevant -->
## Other documentation
<!-- references to upstream documentation, if relevant -->
# Discussion
<!-- the "discussion" section is where you put any longer conversation -->
<!-- about the project that you will not need in a casual -->
<!-- review. history of the project, why it was done the way it was -->
<!-- (as opposed to how), alternatives, and other proposals are -->
<!-- relevant here. -->
<!-- this at least partly overlaps with the TPA-RFC process (see -->
<!-- policy.md), but in general should defer to proposals when -->
<!-- available -->
## Overview
<!-- describe the overall project. should include a link to a ticket -->
<!-- that has a launch checklist -->
<!-- if this is an old project being documented, summarize the known -->
<!-- issues with the project. -->
## Security and risk assessment
<!--
5. When was the last security review done on the project? What was
the outcome? Are there any security issues currently? Should it
have another security review?
6. When was the last risk assessment done? Something that would cover
risks from the data stored, the access required, etc.
-->
## Technical debt and next steps
<!--
7. Are there any in-progress projects? Technical debt cleanup?
Migrations? What state are they in? What's the urgency? What's the
next steps?
8. What urgent things need to be done on this project?
-->
## Proposed Solution
<!-- Link to RFC -->
## Other alternatives
<!-- include benchmarks and procedure if relevant -->