MirrorHub/bitwarden_rs
0
0
Fork 0
mirror of https://github.com/dani-garcia/vaultwarden synced 2024-06-20 12:58:38 +02:00
Code Issues Releases Wiki Activity

Revert changes made by stevo8907 who deleted some pages

BlackDex 2021-10-04 12:03:21 +02:00
parent f7129025bb
commit 23514a8849
No known key found for this signature in database
GPG key ID: 58C80A2AA6C765E1
4 changed files with 324 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
Backing-up-your-vault.md Normal file

@ -0,0 +1,112 @@
## Overview
vaultwarden data should be backed up regularly, preferably via an automated process (e.g., cron job). Ideally, at least one copy should be stored remotely (e.g., cloud storage or a different computer). Avoid relying on filesystem or VM snapshots as a backup method, as these are more complex operations where more things can go wrong, and recovery in such cases can be difficult or impossible for the typical user. Adding an extra layer of encryption on your backups would generally be a good idea (especially if your backup also includes config data like your [[admin token|Enabling-admin-page]]), but you might choose to skip this step if you're confident that your master password (and those of your other users, if any) is strong.
## Backing up data
By default, vaultwarden stores all of its data under a directory called `data` (in the same directory as the `vaultwarden` executable). This location can be changed by setting the [[DATA_FOLDER|Changing-persistent-data-location]] environment variable. If you run vaultwarden with SQLite (this is the most common setup), then the SQL database is just a file in the data folder. If you run with MySQL or PostgreSQL, you will have to dump that data separately -- this is beyond the scope of this article, but a web search will turn up many other tutorials that cover this topic.
When running with the default SQLite backend, the vaultwarden `data` directory has this structure:
```
data
├── attachments # Each attachment is stored as a separate file under this dir.
│ └── <uuid> # (The attachments dir won't be present if no attachments have been created.)
│ └── <random_id>
├── config.json # Stores admin page config; only exists if the admin page has been enabled before.
├── db.sqlite3 # Main SQLite database file.
├── db.sqlite3-shm # SQLite shared memory file (not always present).
├── db.sqlite3-wal # SQLite write-ahead log file (not always present).
├── icon_cache # Site icons (favicons) are cached under this dir.
│ ├── <domain>.png
│ ├── example.com.png
│ ├── example.net.png
│ └── example.org.png
├── rsa_key.der # `rsa_key.*` files are used to sign authentication tokens.
├── rsa_key.pem
├── rsa_key.pub.der
└── sends # Each Send attachment is stored as a separate file under this dir.
└── <uuid> # (The sends dir won't be present if no Send attachments have been created.)
└── <random_id>
```
When running with MySQL or PostgreSQL backends, the directory structure is the same, except there are no SQLite files. You'll still want to back up files in the `data` directory, as well as a dump of your MySQL or PostgreSQL tables.
Each set of files is discussed in more detail next.
### SQLite database files
_**Backup required.**_
The SQLite database file (`db.sqlite3`) stores almost all important vaultwarden data/state (database entries, user/org/device metadata, etc.), with the main exception being attachments, which are stored as separate files on the filesystem.
You should generally use the `.backup` command in the SQLite CLI (`sqlite3`) to back up the database file. This command uses the [Online Backup API](https://www.sqlite.org/backup.html), which SQLite documents as the [best way](https://www.sqlite.org/howtocorrupt.html#_backup_or_restore_while_a_transaction_is_active) to back up a database file that may be in active use. If you can ensure the database will not be in use when a backup runs, you can also use other methods such as the `.dump` command, or simply copying all the SQLite database files (including the `-wal` file, if present).
A basic backup command looks like this, assuming your data folder is `data` (the default):
```
sqlite3 data/db.sqlite3 ".backup '/path/to/backups/db-$(date '+%Y%m%d-%H%M').sqlite3'"
```
You can also use `VACUUM INTO`, which will compact empty space, but takes somewhat more processing time:
```
sqlite3 data/db.sqlite3 "VACUUM INTO '/path/to/backups/db-$(date '+%Y%m%d-%H%M').sqlite3'"
```
Assuming this command is run on January 1, 2021 at 12:34pm (local time), this backs up your SQLite database file to `/path/to/backups/db-20210101-1234.sqlite3`.
You can run this command via a cron job periodically (preferably at least once a day). If you are running via Docker, note that the Docker images do not include an `sqlite3` binary or `cron` daemon, so you would generally install these on the Docker host itself and run the cron job outside of the container. If you really want to run backups from within the container for some reason, you can install any necessary packages during [container startup](https://github.com/dani-garcia/vaultwarden/wiki/Starting-a-Container#customizing-container-startup), or create your own custom Docker image with your preferred `vaultwarden/server:<tag>` image as the parent.
If you want to copy your backup data to cloud storage, [rclone](https://rclone.org/) is a useful tool for interfacing with various cloud storage systems. [restic](https://restic.net/) is another good option, especially if you have larger attachments and want to avoid recopying them as part of each backup.
### The `attachments` dir
_**Backup required.**_
[File attachments](https://bitwarden.com/help/article/attachments/) are the only important class of data not stored in database tables, mainly because they can be arbitrarily large, and SQL databases generally aren't designed to handle large blobs efficiently. This directory won't be present if no file attachments have ever been created.
### The `sends` dir
_**Backup optional.**_
Like regular file attachments, [Send](https://bitwarden.com/help/article/about-send/) file attachments are not stored in database tables. (Send text notes are stored in the database, however.)
Unlike regular attachments, Send attachments are intended to be ephemeral. Therefore, you might choose not to back up this directory if you want to minimize the size of your backups. On the other hand, if it's more important to maintain proper functionality of existing Sends across a restore, then you should back up this directory.
This directory won't be present if no Send attachments have ever been created.
### The `config.json` file
_**Backup recommended.**_
If you use the admin page to configure your vaultwarden instance and don't have your configuration backed up some other way, then you probably want to back up this file so you don't have to figure out your preferred configuration all over again.
Keep in mind that this file does contain some data in plaintext that could be considered sensitive (admin token, SMTP credentials, etc.), so make sure to encrypt this data if you're concerned that someone else might be able to access to it (e.g., when uploaded to cloud storage).
### The `rsa_key*` files
_**Backup recommended.**_
These files are used to sign the JWTs (authentication tokens) of users currently logged in. Deleting them would simply log out each user, forcing them to log in again.
### The `icon_cache` dir
_**Backup optional.**_
The icon cache stores [website icons](https://bitwarden.com/help/article/website-icons/) so that they don't need to be fetched from the login site repeatedly. It's probably not worth backing up unless you really want to avoid refetching a large cache of icons.
## Restoring backup data
Make sure vaultwarden is stopped, and then simply replace each file or directory in the `data` dir with its backed up version.
When restoring a backup created using `.backup` or `VACUUM INTO`, make sure to first delete any existing `db.sqlite3-wal` file, as this could potentially result in database corruption when SQLite tries to recover `db.sqlite3` using a stale/mismatched WAL file. However, if you backed up the database using a straight copy of `db.sqlite3` and its matching `db.sqlite3-wal` file, then you must restore both files as a pair. You don't need to back up or restore the `db.sqlite3-shm` file.
It's a good idea to run through the process of restoring from backup periodically, just to verify that your backups are working properly. When doing this, make sure to move or keep a copy of your original data in case your backups do not in fact work properly.
## Examples
This section contains an index of third-party backup examples. You should review an example thoroughly and understand what it's doing before using it.
* https://github.com/ttionya/vaultwarden-backup
* https://github.com/shivpatel/bitwarden_rs-local-backup
* https://github.com/shivpatel/bitwarden_rs_dropbox_backup
* https://gitlab.com/1O/bitwarden_rs-backup
* https://github.com/jjlin/vaultwarden-backup
* https://github.com/jmqm/vaultwarden_backup

129
Building-binary.md Normal file

@ -0,0 +1,129 @@
This page is primarily for those interested in vaultwarden development, or who have a specific reason for wanting to build their own binary.
Typical users should either [[deploy via Docker|Which-container-image-to-use]], [[extract the pre-built binaries|Pre-built binaries]] from the Alpine-based Docker images, or look for a [[third-party package|Third-party-packages]].
## Dependencies
- `Rust nightly` (strongly recommended to use [rustup](https://rustup.rs/))
- On a Debian based distro some general packages to make sure building should go fine install the following: `build-essential`, `git`
- `OpenSSL` (should be available in path, see [openssl crate docs](https://docs.rs/openssl/0.10.16/openssl/#automatic))
On a Debian based distro, you need to install `pkg-config` and `libssl-dev`
- For the SQlite3 backend on a Debian based distro you need to install `libsqlite3-dev`
- For the MySQL backend on a Debian based distro you need to install `libmariadb-dev-compat` and `libmariadb-dev`
- For the PostgreSQL on a Debian based distro you need to install `libpq-dev` and `pkg-config`
- `NodeJS` (only when compiling the web-vault, install through your system's package manager, use the [prebuilt binaries](https://nodejs.org/en/download/)) or [nodesource binary distribution](https://github.com/nodesource/distributions)
*Note: web-vault currently uses a package base (e.g. node-sass <v4.12) which requires NodeJS v11*
## Run/Compile
### All backends
```sh
# Compile with all backends and run
cargo run --features sqlite,mysql,postgresql --release
# or just compile with all backends (binary located in target/release/vaultwarden)
cargo build --features sqlite,mysql,postgresql --release
```
### SQlite backend
```sh
# Compile with sqlite backend and run
cargo run --features sqlite --release
# or just compile with sqlite (binary located in target/release/vaultwarden)
cargo build --features sqlite --release
```
### MySQL backend
```sh
# Compile with mysql backend and run
cargo run --features mysql --release
# or just compile with mysql (binary located in target/release/vaultwarden)
cargo build --features mysql --release
```
### PostgreSQL backend
```sh
# Compile with postgresql backend and run
cargo run --features postgresql --release
# or just compile with postgresql (binary located in target/release/vaultwarden)
cargo build --features postgresql --release
```
When run, the server is accessible in [http://localhost:8000](http://localhost:8000).
~*Note: A previous [issue](https://github.com/rust-lang/rust/issues/62896) meant that compilation could fail with a segfault due to an incompatibility between the Rust compiler and LLVM. As a work around an older version of the compiler could be used, e.g. ```cargo +nightly-2019-08-27 build --features yourbackend --release```*~
### Install the web-vault
A compiled version of the web vault can be downloaded from [dani-garcia/bw_web_builds](https://github.com/dani-garcia/bw_web_builds/releases).
If you prefer to compile it manually, follow these steps:
*Note: building the Vault needs ~1.5GB of RAM. On systems like a RaspberryPI with 1GB or less, please [enable swapping](https://www.tecmint.com/create-a-linux-swap-file/) or build it on a more powerful machine and copy the directory from there. This much memory is only needed for building it, running vaultwarden with vault needs only about 10MB of RAM.*
- Clone the git repository at [bitwarden/web](https://github.com/bitwarden/web) and checkout the latest release tag (e.g. v2.1.1):
```sh
# clone the repository
git clone https://github.com/bitwarden/web.git web-vault
cd web-vault
# switch to the latest tag
git checkout "$(git tag --sort=v:refname | tail -n1)"
# use the matching jslib commit
git submodule update --init --recursive
```
- Download the patch file from [dani-garcia/bw_web_builds](https://github.com/dani-garcia/bw_web_builds/tree/master/patches) and copy it to the `web-vault` folder.
To choose the version to use, assuming the web vault is version `vX.Y.Z`:
- If there is a patch with version `vX.Y.Z`, use that one
- Otherwise, pick the one with the largest version that is still smaller than `vX.Y.Z`
- Apply the patch
```sh
# In the 'web-vault' directory
git apply vX.Y.Z.patch
```
- Then, build the Vault:
```sh
npm install
# Read the note below (we do use this for our docker builds).
# npm audit fix
npm run dist
```
*Note: You might be asked to run ```npm audit fix``` to fix vulnerability. This will automatically try to upgrade packages to newer version, which might not be compatible and break web-vault functionality``` Use it at your own risk, if you know what you are doing. We do use this on our own releases btw!*
Finally copy the contents of the `build` folder into the destination folder:
- If you run with `cargo run --release`, it's `vaultwarden/web-vault`.
- If you run the compiled binary directly, it's next to the binary, in `vaultwarden/target/release/web-vault`.
## Configuration
The available configuration options are documented in the default `.env` file, and they can be modified by uncommenting the desired options in that file or by setting their respective environment variables. See the Configuration section of this wiki for the main configuration options available.
Note: the environment variables override the values set in the `.env` file.
## More information for deployment
- [Configuring your reverse proxy](https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples)
- [Setting up Autostart via systemd](https://github.com/dani-garcia/vaultwarden/wiki/Setup-as-a-systemd-service)
## How to recreate database schemas for the sqlite backend (for developers)
Install diesel-cli with cargo:
```sh
cargo install diesel_cli --no-default-features --features sqlite-bundled
```
Make sure that the correct path to the database is in the `.env` file.
If you want to modify the schemas, create a new migration with:
```
diesel migration generate <name>
```
Modify the *.sql files, making sure that any changes are reverted in the down.sql file.
Apply the migrations and save the generated schemas as follows:
```sh
diesel migration redo
# This step should be done automatically when using diesel-cli > 1.3.0
# diesel print-schema > src/db/sqlite/schema.rs
```
## How to migrate from SQLite backend to MySQL backend (for developers)
Refer to [using the MySQL backend](https://github.com/dani-garcia/vaultwarden/wiki/Using-the-MySQL-Backend) if you want to migrate from SQLite.
## How to migrate from SQLite backend to PostgreSQL backend (for developers)
Refer to [using the PostgreSQL backend](https://github.com/dani-garcia/vaultwarden/wiki/Using-the-PostgreSQL-Backend) if you want to migrate from SQLite.

20
Disabling-or-overriding-the-Vault-interface-hosting.md Normal file

@ -0,0 +1,20 @@
As a convenience vaultwarden image will also host static files for Vault web interface. You can disable this static file hosting completely by setting the WEB_VAULT_ENABLED variable.
```sh
docker run -d --name vaultwarden \
-e WEB_VAULT_ENABLED=false \
-v /vw-data/:/data/ \
-p 80:80 \
vaultwarden/server:latest
```
Alternatively you can override the Vault files and provide your own static files to host. You can do that by mounting a path with your files over the `/web-vault` directory in the container. Just make sure the directory contains at least `index.html` file.
```sh
docker run -d --name vaultwarden \
-v /path/to/static/files_directory:/web-vault \
-v /vw-data/:/data/ \
-p 80:80 \
vaultwarden/server:latest
```
Note that you can also change the path where vaultwarden looks for static files by providing the `WEB_VAULT_FOLDER` environment variable with the path.

63
_Sidebar.md Normal file

@ -0,0 +1,63 @@
## FAQs
1. [[FAQs]]
## Container Image Usage
1. [[Which container image to use|Which-Container-image-to-use]]
1. [[Starting a container|Starting-a-container]]
1. [[Updating the vaultwarden image|Updating-the-vaultwarden-image]]
1. [[Using Docker Compose|Using-Docker-Compose]]
1. [[Using Podman|Using-Podman]]
## Deployment
1. [[Building your own docker image|Building-your-own-docker-image]]
1. [[Building binary|Building-binary]]
1. [[Pre-built binaries|Pre-built-binaries]]
1. [[Third-party packages|Third-party-packages]]
1. [[Deployment examples|Deployment-examples]]
1. [[Proxy examples|Proxy-examples]]
1. [[Logrotate example|Logrotate example]]
### HTTPS
1. [[Enabling HTTPS|Enabling-HTTPS]]
1. [[Running a private vaultwarden instance with Let's Encrypt certs]]
## Configuration
1. [[Overview|Configuration-overview]]
1. [[Disable registration of new users|Disable-registration-of-new-users]]
1. [[Disable invitations|Disable-invitations]]
1. [[Enabling admin page|Enabling-admin-page]]
1. [[Disable the admin token|Disable-admin-token]]
1. [[Enabling WebSocket notifications|Enabling-WebSocket-notifications]]
1. [[Enabling U2F authentication|Enabling-U2F-authentication]]
1. [[Enabling YubiKey OTP authentication|Enabling-Yubikey-OTP-authentication]]
1. [[Changing persistent data location|Changing-persistent-data-location]]
1. [[Changing the API request size limit|Changing-the-API-request-size-limit]]
1. [[Changing the number of workers|Changing-the-number-of-workers]]
1. [[SMTP configuration|SMTP-configuration]]
1. [[Password hint display|Password-hint-display]]
1. [[Disabling or overriding the Vault interface hosting|Disabling-or-overriding-the-Vault-interface-hosting]]
1. [[Logging|Logging]]
1. [[Creating a systemd service|Setup-as-a-systemd-service]]
1. [[Running with systemd-docker|Running-with-systemd-docker]]
1. [[Syncing users from LDAP|Syncing-users-from-LDAP]]
1. [[Using an alternate base dir (subdir/subpath)|Using-an-alternate-base-dir]]
1. [[Other configuration|Other-configuration]]
### Database
1. [[Using the MariaDB (MySQL) Backend]]
1. [[Using the PostgreSQL Backend]]
1. [[Running without WAL enabled|Running-without-WAL-enabled]]
### Security
1. [[Hardening Guide|Hardening Guide]]
1. [[Fail2Ban Setup|Fail2Ban-Setup]]
## Backup
1. [[General (not docker)]]
## Other Information
1. [[Importing data from Keepass or KeepassX|Importing-data-from-Keepass-or-KeepassX]]
1. [[Backing up your vault|Backing-up-your-vault]]
1. [[Differences from the upstream API implementation|Differences-from-the-upstream-API-implementation]]
1. [[Supporting upstream development|Supporting-upstream]]
1. [[Caddy 2.x with Cloudflare DNS]]