vaultwarden¶

Bitwarden is an open source password manager. Your vault is encrypted with your master key, so even if your server is compromised the hacker will only get some unreadable gibberish. Hosting your own Bitwarden server can be useful if you are paranoid about the server security and want to be in full control, or want the premium features for free because you have a webspace anyway.

Note

The installation of the official bitwarden server repository via docker is heavy, difficult and relies on docker, which isn’t supported at Uberspace due to the fact of shared hosting. In this guide we’ll use the Rust implementation vaultwarden (formerly Bitwarden_rs) of the Bitwarden API, so you can still use the official clients.

Note

For this guide you should be familiar with the basic concepts of

License¶

vaultwarden is released under the GNU General Public License version 3.

Prerequisites¶

If you want to use vaultwarden with your own domain you need to set up your domain first:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation¶

Install vaultwarden¶

We will be installing vaultwarden by extracting a standalone, statically-linked binary from the official Docker image.

Create a directory in /home/isabell for vaultwarden. In the vaultwarden directory, also create a directory to store the actual data.

[isabell@stardust ~]$ mkdir ~/vaultwarden
[isabell@stardust ~]$ mkdir ~/vaultwarden/data
[isabell@stardust ~]$

Download the Docker Image Extractor.

[isabell@stardust ~]$ wget -O ~/vaultwarden/docker-image-extract https://raw.githubusercontent.com/jjlin/docker-image-extract/main/docker-image-extract
[isabell@stardust ~]$

Change into the ~/vaultwarden directory. Fetch and extract the binary from the appropriate image.

[isabell@stardust ~]$ cd ~/vaultwarden
[isabell@stardust vaultwarden]$ chmod +x docker-image-extract
[isabell@stardust vaultwarden]$ ./docker-image-extract vaultwarden/server:alpine
Getting API token...
Getting image manifest for vaultwarden/server:alpine...
Downloading layer 8516f4cd818630cd60fa18254b072f8d9c3748bdb56f6e2527dc1c204e8e017c...
Extracting layer...
...
Image contents extracted into ./output.
[isabell@stardust vaultwarden]$

Update default configuration¶

Use your favourite editor to create ~/vaultwarden/.env with the following content:

SMTP_HOST=stardust.uberspace.de
SMTP_FROM=isabell@uber.space
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=isabell@uber.space
SMTP_PASSWORD=MySuperSecretPassword
DOMAIN=https://isabell.uber.space
ROCKET_ADDRESS=0.0.0.0
ROCKET_PORT=8000

Replace the mail placeholder variables with your valid SMTP credentials, otherwise the vaultwarden server will not be able to send you mail notifications or tokens to verify newly created user accounts. SMTP_USERNAME and SMTP_PASSWORD must be the login data from a valid mail account. Replace the server domain with your final URL.

Note

You can configure any type of service here, you’re not limited to an uberspace SMTP user. If you prefer e.g. gmail refer to their documentations for SMTP_PORT etc. accordingly.

You can edit other options, look into .env.template to see a list of available options.

Configuration¶

Setup web backend¶

Note

vaultwarden will run on port 8000 (you can change this in the .env config file).

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

If you want to use a subdomain refer to the web-backend manual.

Setup web vault¶

Now it’s time to test if everything works.

Note

Setting both ENV_FILE and DATA_FOLDER as temporary environment variables is necessary for vaultwarden to find the correct config and data directory.

[isabell@stardust ~]$ export ENV_FILE=$HOME/vaultwarden/.env
[isabell@stardust ~]$ export DATA_FOLDER=$HOME/vaultwarden/data
[isabell@stardust ~]$ cd ~/vaultwarden/output
[isabell@stardust output]$ ./vaultwarden
/--------------------------------------------------------------------\
|                       Starting Vaultwarden                         |
|                          Version 1.23.1                            |
|--------------------------------------------------------------------|
| This is an *unofficial* Bitwarden implementation, DO NOT use the   |
| official channels to report bugs/features, regardless of client.   |
| Send usage/configuration questions or feature requests to:         |
|   https://vaultwarden.discourse.group/                             |
| Report suspected bugs/issues in the software itself at:            |
|   https://github.com/dani-garcia/vaultwarden/issues/new            |
\--------------------------------------------------------------------/
Running migration 20180711181453
Running migration 20180827172114
...
[2021-12-29 10:40:35.407][start][INFO] Rocket has launched from http://0.0.0.0:8000

If there is no error, you are good to go. You should be able to access your vault on https://isabell.uber.space

Setup daemon¶

Use your favourite editor to create ~/etc/services.d/vaultwarden.ini with the following content:

[program:vaultwarden]
directory=%(ENV_HOME)s/vaultwarden/output/
command=%(ENV_HOME)s/vaultwarden/output/vaultwarden
autostart=yes
autorestart=yes
startsecs=60
environment=ENV_FILE="%(ENV_HOME)s/vaultwarden/.env",DATA_FOLDER="%(ENV_HOME)s/vaultwarden/data"

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration. You can check the service’s log file using supervisorctl tail -f vaultwarden.

Finishing installation¶

You are done. Point your Browser to your installation URL https://isabell.uber.space and create your user.

Admin Page¶

The admin page allows you to view all the registered users and to delete them. It also allows inviting new users, even when registration is disabled.

Enabling Admin Page¶

The admin page is disabled by default.

To enable it, you should create a secure, long password and save the hash of that password into your ~/vaultwarden/.env.

You can create the hash with the built in hash command:

[isabell@stardust ~]$ cd ~/vaultwarden/output
[isabell@stardust ~]$ ./vaultwarden hash
Generate an Argon2id PHC string using the 'bitwarden' preset:

Password:
Confirm Password:

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$Ghv9VB ... SDSMvJbhDVlU'

Generation of the Argon2id PHC string took: 401.754824ms
[isabell@stardust ~]$

Now you have to paste the result of the command into your ~/vaultwarden/.env file:

SMTP_HOST=stardust.uberspace.de
SMTP_FROM=isabell@uber.space
SMTP_PORT=587
SMTP_SECURITY=starttls
SMTP_USERNAME=isabell@uber.space
SMTP_PASSWORD=MySuperSecretPassword
DOMAIN=https://isabell.uber.space
ROCKET_ADDRESS=0.0.0.0
ROCKET_PORT=8000
ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$Ghv9VB ... SDSMvJbhDVlU'

To make sure your changes take effect, restart the service:

[isabell@stardust ~]$ supervisorctl restart vaultwarden

When enabled, you can access it by pointing your browser to https://isabell.uber.space/admin.

Note

Be careful when editing values via the Admin-Page as they overrule your settings in the ~/vaultwarden/.env file.

Best practices¶

Backing up your vault manually¶

You can create a backup of the database manually. cd to your project folder, create a folder to store the backup in and use the given sqlite3 backup command. This will ensure the database does not become corrupted if the backup happens during a database write.

[isabell@stardust ~]$ mkdir ~/vaultwarden/data/db-backup
[isabell@stardust ~]$ sqlite3 ~/vaultwarden/data/db.sqlite3 ".backup '$HOME/vaultwarden/data/db-backup/backup.sqlite3'"

Note

You could run this command through a CRON job everyday - note that it will overwrite the same backup.sqlite3 file each time. If you want to save every version of the backup, please read further.

Alternatively, you can do the backup with a timestamp and it can be useful if you don’t want that the CRON job overwrites the backup file. $(date +%Y-%m-%d) in the file name in the following command will generate a name with current year, month and day.

[isabell@stardust ~]$ sqlite3 ~/vaultwarden/data/db.sqlite3 ".backup '$HOME/vaultwarden/data/db-backup/$(date +%Y-%m-%d).sqlite3'"

To do this, create a bash script with the last command and save it as ~/backup-vaultwarden.sh and make it executable.

[isabell@stardust ~]$ chmod +x backup-vaultwarden.sh

Now you can add this script into your crontab.

Restore up your vault manually¶

Before you restore a database backup make sure to stop the service:

[isabell@stardust ~]$ supervisorctl stop vaultwarden

To restore your database simply overwrite db.sqlite3 with backup.sqlite3 or the one with a specific timestamp. After replacing the file successfully you can restart the service again.

[isabell@stardust ~]$ supervisorctl restart vaultwarden

Hardening¶

Disable registration and invitations¶

By default, vaultwarden allows any anonymous user to register new accounts on the server without first being invited. This is necessary to create your first user on the server, but it’s recommended to disable it in the admin panel (if the admin panel is enabled) or with the environment variable to prevent attackers from creating accounts on your vaultwarden server.

Use your favourite editor to edit ~/vaultwarden/.env and add the following content:

SIGNUPS_ALLOWED=false

Note

While through this setting users can’t register on their own, they can still be invited by already registered users to create accounts on the server and join their organizations. This does not pose an immediate risk (as long as you trust your users), but it can be disabled in the admin panel or with the following environment variable:

INVITATIONS_ALLOWED=false

In addition to SIGNUPS_ALLOWED=false you can create an except for specific domains. Make sure to sue this setting only in addition to SIGNUPS_ALLOWED=false!

SIGNUPS_DOMAINS_WHITELIST=example.com # single domain
SIGNUPS_DOMAINS_WHITELIST=example.com,example.net,example.org # multiple domains

Warning

be careful using this feature. At the moment the emails are currently not checked, meaning that anyone could still register, by providing a fake email address that has the proper domain. So at the moment this is more security by obscurity. This seems to be fixed in an upcoming release, so make sure to check the feed regularly to stay informed about the newest version.

Disable password hint display¶

vaultwarden displays password hints on the login page to accommodate small/local deployments that do not have SMTP configured, which could be abused by an attacker to facilitate password-guessing attacks against users on the server. This can be disabled in the admin panel by unchecking the Show password hints option or with the environment variable:

Use your favourite editor to edit ~/vaultwarden/.env and add the the following content:

SHOW_PASSWORD_HINT=false

Updates¶

Note

Check the update feed regularly to stay informed about the newest version.

Warning

Be careful while upgrading. Have a backup of the data before attempting upgrade.

Updating vaultwarden is really easy.

Stop the server
Backup data and .env
Pull latest image and extract binary
Start the server again

[isabell@stardust ~]$ cd ~/vaultwarden
[isabell@stardust vaultwarden]$ supervisorctl stop vaultwarden
vaultwarden: stopped
[isabell@stardust vaultwarden]$ ./docker-image-extract vaultwarden/server:alpine
Getting API token...
Getting image manifest for vaultwarden/server:alpine...
Fetching and extracting layer 97518928ae5f3d52d4164b314a7e73654eb686ecd8aafa0b79acd980773a740d...
...
Image contents extracted into ./output.
[isabell@stardust vaultwarden]$ supervisorctl start vaultwarden
vaultwarden: started
[isabell@stardust vaultwarden]$

Hint: If the update fails¶

When you get the error message No layers returned. Verify that the image and tag are valid. you’ll have to update the Docker Image Extractor first as described below:

[isabell@stardust ~]$ cd ~/vaultwarden
[isabell@stardust ~]$ rm docker-image-extract
[isabell@stardust ~]$ wget -O ~/vaultwarden/docker-image-extract https://raw.githubusercontent.com/jjlin/docker-image-extract/main/docker-image-extract
[isabell@stardust ~]$ chmod +x docker-image-extract
[isabell@stardust ~]$

Acknowledgements¶

This guide is based on the official vaultwarden documentation. Previously, it was based on the bitwarden_rs guide from Tom Schneider.

Tested with vaultwarden 1.23.1 and Web-Vault v2.25.0, Uberspace 7.12

Written by: Achim | pxlfrk <hallo@pxlfrk.de>, knhash <https://knhash.in>