lasers/bitwarden_rs
1
0
Fork 0
mirror of https://github.com/dani-garcia/bitwarden_rs synced 2024-11-21 17:36:41 +01:00
Code Issues Projects Releases Wiki Activity
Page: Configuration overview
Pages
Audits Backing up your vault Building binary Building your own docker image Caddy 2.x with Cloudflare DNS Changing persistent data location Changing the API request size limit Changing the number of workers Configuration overview Customize Vaultwarden CSS Deployment examples Differences from the upstream API implementation Disable admin token Disable invitations Disable registration of new users Disabling or overriding the Vault interface hosting Docker Traefik ModSecurity Setup Enable admin page Enabling HTTPS Enabling Mobile Client push notification Enabling U2F (and FIDO2 WebAuthn) authentication Enabling U2F authentication Enabling WebSocket notifications Enabling Yubikey OTP authentication Enabling admin page secure the admin_token Enabling admin page FAQs Fail2Ban Setup General (not docker) Hardening Guide Home Importing data from Keepass or KeepassX Kubernetes deployment Logging Logrotate example Migrating from MariaDB (MySQL) to SQLite Other configuration Password hint display Pre built binaries Private CA and self signed certs that work with Chrome Proxy examples Running a private vaultwarden instance with Let's Encrypt certs Running docker container with non root user Running without WAL enabled SMTP Configuration Setup as a systemd service Starting a Container Supporting upstream Syncing users from LDAP Testing SSO Third party packages Translating the email templates Updating the vaultwarden image Using Docker Compose Using Podman Using an alternate base dir Using the MariaDB (MySQL) Backend Using the MySQL Backend Using the PostgreSQL Backend Which container image to use
16 Configuration overview
Stefan Melmuk edited this page 2024-06-12 01:52:17 +02:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

How to configure Vaultwarden

There are basically three different ways to configure Vaultwarden:

  1. setting up environment variables,
  2. using an ENV_FILE and
  3. via a config.json, not recommended (which can be generated and managed via the admin page).

You can find a documented list of most configuration options in the .env.template file. Typically the commented values will indicate the default values but that is not a guarantee. In case it's not, the source of truth will be src/config.rs.

If you enable the admin page, you can also see the configuration options with the configured values (and if you are using config.json an indication whether the value has been changed from the initial value).

Note

Be aware that the config.json file is NOT the recommended way to configure your settings! Either use environment variables which you can configure in several ways for your container environment (Docker, Docker-Compose, K8s etc..) Or, when using a standalone binary (not distributed by Vaultwarden itself) use a .env file located in your current working directory.

If you rely on a third-party package you will have to check the provided documentation (e.g. installation notice of Arch Linux' vaultwarden package), as the downstream maintainers usually make some assumptions for their package.

Using environment variables

The recommended way to configure Vaultwarden is via environment variables. Depending on how you run Vaultwarden (e.g. directly, in a containerized environment, via systemd, etc.), there are different ways to set the environment variables, so familiarize yourself with your platform and method of installation.

Most environment variables that can be set are found in the .env.template file. You can also use that file as a basis for an environment file for your container environment (e.g. via an env_file attribute) or with a systemd service (c.f. EnvironmentFile=) – just don't confuse this file with the ENV_FILE method below!

Tip

Be aware that there might be some subtle differences between the different platforms for how an environment file is interpreted (in regards to variable expansion or whether you can or should use quotation marks around the values, etc).

You also need to make sure that you set the variable in the correct environment. If you use a containerized environment the vaultwarden process will be running isolated from the host platform. This is especially relevant if you use a container management platform that you can set environment variables for (e.g. when using docker-compose). Because typically those environment variables can then be used in the creation of a container but they will not be passed down into the running container.

Note

A container configured like this with environment variables needs to be recreated if you change a value because the values are bound to the container. So unless the value is read from a (changed) file a restart will not do anything.

Using an ENV_FILE

Vaultwarden can also directly read the configuration options from an environment file itself, which is especially useful when developing Vaultwarden.

By default Vaultwarden will try to read a file called .env from the current working directory (e.g. if you run cargo run from the root of the checked-out repository it should be in the same root directory).

Tip

There is a difference between using an environment file to setup the runtime environment of the process (whether with something like docker or systemd) and using an env file in Vaultwarden. E.g. instead of passing an environment file via --env-file (which is read when the container is created) you could also mount the environment file to /.env when using a container image. (C.f. the explanation above.)

The values that are set directly in the environment will take precedence over this method. That means the values can be overridden without changing the values in the ENV_FILE (which might be useful for debugging purposes, e.g. when you temporarily set LOG_LEVEL=debug).

Loading individual values from files

Vaultwarden supports loading the values of the configuration options (both by environment variables or if set in the ENV_FILE) from the disk. You can achieve this by adding _FILE to the configuration option in question and setting the value to the path to a file containing the value.

This is useful if you want to use a feature like docker secrets, e.g. by setting SMTP_PASSWORD_FILE=/run/secrets/smtp_password it would load SMTP password from the file without making it available to the process or the container as an environment variable).

Using the /admin page

To an extend, Vaultwarden can also be configured using a config.json file, which can be generated and edited over the /admin panel and is saved in the data folder.

Important

🙏 While it's technically possible to create and edit the config.json file manually, we strongly advise against it. JSON has a rather strict syntax and if you don't know what you are doing, this might become a nightmare to debug.

The settings in config.json will override any other configuration method and you will be warned on startup which settings have been overwritten by config.json.

Since this generated config.json will include all editable options when saved, be aware that once you generate the configuration file via the /admin page, you cannot modify those options via any of the other methods (at least not without modifying or removing the config.json file).

Note

The options in the section Read-Only Config cannot be modified via the /admin page because they require a server restart and they will be removed if you have added them manually to the config.json and click on save. Use the other methods described above to modify them. In most cases this means that you also need to recreate the container!

Some environment variables are not part of Vaultwardens configuration system and therefore cannot be set via config.json (e.g. ROCKET_ADDRESS or ROCKET_PORT).

Configuration precedence

  1. On compilation the defaults are hard coded via src/config.rs.
  2. Those defaults can be changed without recompiling the binary by providing an ENV_FILE and also
  3. by setting the environment variables (which will overrule settings in the ENV_FILE).
  4. The end user (with access to /admin panel) optionally can create a config.json which will take the highest precedence.

Setting the domain URL

Make sure to set the DOMAIN environment variable (or domain in the config file) to the base URL of your Vaultwarden instance. If you don't, it is likely that some functionality might break mysteriously. Some examples:

  • https://bitwarden.example.com
  • https://bitwarden.example.com:8443 (non-default port)
  • https://host.example.com/bitwarden/ (subdir hosting -- avoid URL-rewriting tricks whenever possible)

Further information about different configuration options

FAQs

  1. FAQs
  2. Audits

Container Image Usage

  1. Which container image to use
  2. Starting a container
  3. Updating the vaultwarden image
  4. Using Docker Compose
  5. Using Podman

Deployment

  1. Building your own docker image
  2. Building binary
  3. Pre-built binaries
  4. Third-party packages
  5. Deployment examples
  6. Proxy examples
  7. Logrotate example

HTTPS

  1. Enabling HTTPS
  2. Running a private vaultwarden instance with Let's Encrypt certs

Configuration

  1. Overview
  2. Disable registration of new users
  3. Disable invitations
  4. Enabling admin page
  5. Disable the admin token
  6. Enabling WebSocket notifications
  7. Enabling Mobile Client push notification
  8. Enabling U2F and FIDO2 WebAuthn authentication
  9. Enabling YubiKey OTP authentication
  10. Changing persistent data location
  11. Changing the API request size limit
  12. Changing the number of workers
  13. SMTP configuration
  14. Translating the email templates
  15. Password hint display
  16. Disabling or overriding the Vault interface hosting
  17. Logging
  18. Creating a systemd service
  19. Syncing users from LDAP
  20. Using an alternate base dir (subdir/subpath)
  21. Other configuration

Database

  1. Using the MariaDB (MySQL) Backend
  2. Using the PostgreSQL Backend
  3. Running without WAL enabled
  4. Migrating from MariaDB (MySQL) to SQLite

Security

  1. Hardening Guide
  2. Fail2Ban Setup
  3. Fail2Ban + ModSecurity + Traefik + Docker

Backup

  1. General (not docker)

Other Information

  1. Importing data from Keepass or KeepassX
  2. Backing up your vault
  3. Differences from the upstream API implementation
  4. Supporting upstream development
  5. Caddy 2.x with Cloudflare DNS