Skip to content

Vaultwarden

Vaultwarden

License: AGPLv3

This guide is tested with Vaultwarden 1.35.3 on Uberspace 8.0.66. We can't guarantee it to work with newer versions.

Vaultwarden ist an alternative server implementation of the Bitwarden Client API, written in Rust and compatible with official Bitwarden clients. You an use it to generate, store, and sync your passwords.

Note

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

Prerequisites

Rust is already pre-installed, there is nothing to do here.

You'll need your MySQL credentials:

[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword

Preperation

Create a directory to store vaultwarden files and change into it.

[isabell@moondust ~]$ mkdir ~/vaultwarden

Compilation

Download, extract, and compile vaultwarden:

[isabell@moondust ~]$ cd ~/vaultwarden
[isabell@moondust vaultwarden]$ curl -Lso - https://github.com/dani-garcia/vaultwarden/archive/refs/tags/1.35.3.tar.gz | tar xz
[isabell@moondust vaultwarden]$ cd vaultwarden-1.35.3
[isabell@moondust vaultwarden-1.35.3]$ cargo build --release --features sqlite
    Updating crates.io index
  Downloaded ecdsa v0.16.9
  Downloaded hostname v0.4.2
  Downloaded futures-util v0.3.32
  Downloaded lasso v0.7.3
  Downloaded num-derive v0.4.2
  Downloaded num_cpus v1.17.0
  Downloaded pear_codegen v0.2.9
   (...)
   Compiling yubico_ng v0.14.1
   Compiling diesel v2.3.6
   Compiling openidconnect v4.0.1
   Compiling rocket_ws v0.1.1
   Compiling diesel_migrations v2.3.1
    Finished `release` profile [optimized] target(s) in 18m 26s
[isabell@moondust vaultwarden-1.35.3]$ cd ~

Note

The cargo build ... command can take a while to finish. Do not cancel it.

Installation

Copy the compiled binary to ~/bin/ for easier use and create a directory to store vaultwarden files.

[isabell@moondust ~]$ cd ~/vaultwarden/vaultwarden-1.35.3/
[isabell@moondust vaultwarden-1.35.3]$ cp target/release/vaultwarden ~/bin/
[isabell@moondust vaultwarden-1.35.3]$ chmod +x ~/bin/vaultwarden
[isabell@moondust vaultwarden-1.35.3]$ cd ~

Change into the ~/vaultwarden directory, then download and install the files needed for the web interface:

[isabell@moondust ~]$ cd ~/vaultwarden
[isabell@moondust ~/vaultwarden]$ curl -Lso - https://github.com/dani-garcia/bw_web_builds/releases/download/v2026.1.1/bw_web_v2026.1.1.tar.gz | tar xz
[isabell@moondust ~/vaultwarden]$ cd ~

Configuration

Use your favorite 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 another mail provider, refer to their documentations and set SMTP_PORT, etc. accordingly.

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

Service

Create a web backend to expose vaultwarden to the web:

[isabell@moondust ~]$ uberspace web backend add / PORT 8000 --force
OK: Added webbackend '/' to your Asteroid

Then, create a service to run vaultwarden permanently in the background:

[isabell@moondust ~]$ uberspace service add vaultwarden $HOME/bin/vaultwarden --env ENV_FILE="$HOME/vaultwarden/.env" --env DATA_FOLDER="$HOME/vaultwarden/data" --workdir $HOME/vaultwarden

Finishing installation

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

Additional Steps

Enabling 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 and 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 ~]$ 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

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

(...)
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 ~]$ systemctl --user 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.

Disabling Admin Page again

To deactivate the admin page again, edit the file ~/vaultwarden/data/config.json and clear the value of admin_token

Before

"admin_token": "$argon2id$v=19$m=65540,t=3,p=4$Ghv9VB ... SDSMvJbhDVlU",

After

"admin_token": "",

and restart the service for the changes to take effect.

[isabell@stardust ~]$ systemctl --user restart vaultwarden

Leave the file ~/vaultwarden/.env as it has no effect on the admin page.

The admin page at https://isabell.uber.space/admin should no longer be accessible.

Reenable admin page

Copy the value of ADMIN_TOKEN from the file ~/vaultwarden/.env

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

back into the file ~/vaultwarden/data/config.json

"admin_token": "$argon2id$v=19$m=65540,t=3,p=4$Ghv9VB ... SDSMvJbhDVlU",

Restart the service:

[isabell@stardust ~]$ systemctl --user restart vaultwarden

The admin page is accessible again.

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 ~]$ sqlite3 ~/vaultwarden/data/db.sqlite3 ".backup '$HOME/vaultwarden/data/db-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'"

Restore up your vault manually

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

[isabell@stardust ~]$ systemctl --user stop vaultwarden

To restore your database simply overwrite db.sqlite3 with backup.sqlite3 or the one with a specific timestamp. After replacing the file, restart the service:

[isabell@stardust ~]$ systemctl --user 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 use 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 following content:

SHOW_PASSWORD_HINT=false

Debugging

Check the journal for any error messages:

[isabell@moondust ~]$ journalctl --user --unit vaultwarden
Feb 19 13:33:37 moondust.uberspace.de systemd[1260086]: Started vaultwarden.service.
Feb 19 13:33:37 moondust.uberspace.de vaultwarden[1312248]: /----------------------\
Feb 19 13:33:37 moondust.uberspace.de vaultwarden[1312248]: | Starting Vaultwarden |
(...)

Updates

Note

Check the vaultwaren update feed and the vaultwaren web update feed regularly.

To update, stop the service using systemctl --user stop vaultwarden, repeat the Compilation and Installation steps, then start the service again using systemctl --user start vaultwarden.