Vaultwarden Service
Table of Contents
Defined in /modules/services/vaultwarden.nix.
This NixOS module is a service that sets up a Vaultwarden Server.
Features
Access through subdomain using reverse proxy.
Access through HTTPS using reverse proxy.
Automatic setup of Redis database for caching.
Backup of the data directory through the backup contract.
Tests /admin can only be accessed when authenticated with SSO.
Integration with the dashboard contract for displaying user facing application in a dashboard.
Usage
Initial Configuration
The following snippet enables Vaultwarden and makes it available under the vaultwarden.example.com endpoint.
shb.vaultwarden = {
enable = true;
domain = "example.com";
subdomain = "vaultwarden";
port = 8222;
databasePassword.result = config.shb.sops.secret."vaultwarden/db".result;
smtp = {
host = "smtp.eu.mailgun.org";
port = 587;
username = "postmaster@mg.${domain}";
from_address = "authelia@${domain}";
passwordFile = config.sops.secrets."vaultwarden/smtp".path;
};
};
shb.sops.secret."vaultwarden/db".request = config.shb.vaultwarden.databasePassword.request;
shb.sops.secret."vaultwarden/smtp".request = config.shb.vaultwarden.smtp.password.request;
This assumes secrets are setup with SOPS
as mentioned in the secrets setup section of the manual.
Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.
The SMTP configuration is needed to invite users to Vaultwarden.
HTTPS
If the shb.ssl block is used (see manual on how to set it up),
the instance will be reachable at https://vaultwarden.example.com.
Here is an example with Let’s Encrypt certificates, validated using the HTTP method:
shb.certs.certs.letsencrypt."example.com" = {
domain = "example.com";
group = "nginx";
reloadServices = [ "nginx.service" ];
adminEmail = "myemail@mydomain.com";
};
Then you can tell Vaultwarden to use those certificates.
shb.certs.certs.letsencrypt."example.com".extraDomains = [ "vaultwarden.example.com" ];
shb.forgejo = {
ssl = config.shb.certs.certs.letsencrypt."example.com";
};
SSO
To protect the /admin endpoint and avoid needing a secret passphrase for it, we can use SSO.
We will use the SSO block provided by Self Host Blocks. Assuming it has been set already, add the following configuration:
shb.vaultwarden.authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
Now, go to the LDAP server at https://ldap.example.com,
create the vaultwarden_admin group and add a user to that group.
When that’s done, go back to the Vaultwarden server at
https://vaultwarden.example.com/admin and login with that user.
ZFS
Integration with the ZFS block allows to automatically create the relevant datasets.
shb.zfs.datasets."vaultwarden" = config.shb.vaultwarden.mount;
shb.zfs.datasets."postgresql".path = "/var/lib/postgresql";
Backup
Backing up Vaultwarden using the Restic block is done like so:
shb.restic.instances."vaultwarden" = {
request = config.shb.vaultwarden.backup;
settings = {
enable = true;
};
};
The name "vaultwarden" in the instances can be anything.
The config.shb.vaultwarden.backup option provides what directories to backup.
You can define any number of Restic instances to backup Vaultwarden multiple times.
Application Dashboard
Integration with the dashboard contract is provided by the dashboard option.
For example using the Homepage service:
{
shb.homepage.servicesGroups.Documents.services.Vaultwarden = {
sortOrder = 10;
dashboard.request = config.shb.vaultwarden.dashboard.request;
};
}
Maintenance
No command-line tool is provided to administer Vaultwarden.
Instead, the admin section can be found at the /admin endpoint.
Debug
In case of an issue, check the logs of the vaultwarden.service systemd service.
Enable verbose logging by setting the shb.vaultwarden.debug boolean to true.
Access the database with sudo -u vaultwarden psql.
Options Reference
-
shb.vaultwarden.enable -
Whether to enable selfhostblocks.vaultwarden.
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.authEndpoint -
OIDC endpoint for SSO
Type: null or string
Default:
nullExample:
"https://authelia.example.com"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup -
Backup configuration.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request -
Request part of the backup contract.
Options set by the requester module enforcing how to backup files.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.excludePatterns -
File patterns to exclude.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.hooks -
Hooks to run around the backup.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.hooks.afterBackup -
Hooks to run after backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.hooks.beforeBackup -
Hooks to run before backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.sourceDirectories -
Directories to backup.
Type: non-empty (list of string)
Default:
[ "/var/lib/vaultwarden" ]Example:
"/var/lib/vaultwarden"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.request.user -
Unix user doing the backups.
Type: string
Default:
"vaultwarden"Example:
"vaultwarden"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.result -
Result part of the backup contract.
Options set by the provider module that indicates the name of the backup and restore scripts.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.result.backupService -
Name of service backing up the database.
This script can be ran manually to backup the database:
$ systemctl start backup.serviceType: string
Default:
"backup.service"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.backup.result.restoreScript -
Name of script that can restore the database. One can then list snapshots with:
$ restore snapshots <snapshot 1> <metadata> <snapshot 2> <metadata>And restore the database with:
$ restore restore <snapshot 1>Type: string
Default:
"restore"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.dashboard -
Dashboard contract consumer
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.dashboard.request -
Request part of the dashboard contract.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.dashboard.request.externalUrl -
URL at which the service can be accessed.
This URL should go through the reverse proxy.
Type: string
Default:
"https://\${config.shb.vaultwarden.subdomain}.\${config.shb.vaultwarden.domain}"Example:
"https://jellyfin.example.com"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.dashboard.request.internalUrl -
URL at which the service can be accessed directly.
This URL should bypass the reverse proxy. It can be used for example to ping the service and making sure it is up and running correctly.
Type: null or string
Default:
"http://127.0.0.1:8222"Example:
"http://127.0.0.1:8081"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.dashboard.result -
Result part of the dashboard contract.
No option is provided here.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword -
File containing the Vaultwarden database password.
Type: submodule
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.request -
Request part of the secret contract.
Options set by the requester module enforcing some properties the secret should have.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.request.group -
Linux group owning the secret file.
Type: string
Default:
"postgres"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.request.mode -
Mode of the secret file.
Type: string
Default:
"0440"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.request.owner -
Linux user owning the secret file.
Type: string
Default:
"vaultwarden"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ "vaultwarden.service" "postgresql.service" ]Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.result -
Result part of the secret contract.
Options set by the provider module that indicates where the secret can be found.
Type: submodule
Default:
{ path = "/run/secrets/secret"; }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.databasePassword.result.path -
Path to the file containing the secret generated out of band.
This path will exist after deploying to a target host, it is not available through the nix store.
Type: absolute path
Default:
"/run/secrets/secret"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.debug -
Set to true to enable debug logging.
Type: boolean
Default:
falseExample:
trueDeclared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.domain -
domain under which Authelia will be served.
Type: string
Example:
"mydomain.com"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.mount -
Mount configuration. This is an output option.
Use it to initialize a block implementing the “mount” contract. For example, with a zfs dataset:
shb.zfs.datasets."vaultwarden" = { poolName = "root"; } // config.shb.vaultwarden.mount;Type: open submodule of anything (read only)
Default:
{ path = "/var/lib/vaultwarden"; }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.mount.path -
Path to be mounted.
Type: string
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.port -
Port on which vaultwarden service listens.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
8222Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp -
SMTP options.
Type: null or (submodule)
Default:
nullDeclared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.auth_mechanism -
Auth mechanism.
Type: value “Login” (singular enum)
Default:
"Login"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.from_address -
SMTP address from which the emails originate.
Type: string
Example:
"vaultwarden@mydomain.com"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.from_name -
SMTP name from which the emails originate.
Type: string
Default:
"Vaultwarden"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.host -
SMTP host to send the emails to.
Type: string
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password -
File containing the password to connect to the SMTP host.
Type: submodule
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.request -
Request part of the secret contract.
Options set by the requester module enforcing some properties the secret should have.
Type: submodule
Default:
""Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.request.group -
Linux group owning the secret file.
Type: string
Default:
"root"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.request.mode -
Mode of the secret file.
Type: string
Default:
"0400"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.request.owner -
Linux user owning the secret file.
Type: string
Default:
"vaultwarden"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.request.restartUnits -
Systemd units to restart after the secret is updated.
Type: list of string
Default:
[ "vaultwarden.service" ]Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.result -
Result part of the secret contract.
Options set by the provider module that indicates where the secret can be found.
Type: submodule
Default:
{ path = "/run/secrets/secret"; }Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.password.result.path -
Path to the file containing the secret generated out of band.
This path will exist after deploying to a target host, it is not available through the nix store.
Type: absolute path
Default:
"/run/secrets/secret"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.port -
SMTP port to send the emails to.
Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
25Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.security -
Security expected by SMTP host.
Type: one of “starttls”, “force_tls”, “off”
Default:
"starttls"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.smtp.username -
Username to connect to the SMTP host.
Type: string
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.ssl -
Path to SSL files
Type: null or (open submodule of anything)
Default:
nullDeclared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.ssl.paths -
Paths where the files for the certificate will be located.
This option is the contract output of the
shb.certs.certsSSL block.Type: open submodule of anything
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.ssl.paths.cert -
Path to the cert file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.ssl.paths.key -
Path to the key file.
Type: absolute path
Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.ssl.systemdService -
Systemd oneshot service used to generate the certificate. Ends with the
.servicesuffix.Use this if downstream services must wait for the certificates to be generated before starting.
Type: string
Example:
"cert-generator.service"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix> -
shb.vaultwarden.subdomain -
Subdomain under which Authelia will be served.
Type: string
Example:
"ha"Declared by:
<selfhostblocks/modules/services/vaultwarden.nix>