# 使用

## 配置 SMTP <a href="#configure-smtp" id="configure-smtp"></a>

Bitwarden 的很多日常验证场景，比如新账户邮件地址的验证、邀请用户、管理门户的使用等，严重依赖 SMTP 功能。部署好 Bitwarden 后，第一步就应该配置 SMTP。

根据您的电子邮件服务提供商关于 SMTP 的说明，修改环境配置文件 `./bwdata/env/global.override.env` 中的如下变量的值：

```systemd
globalSettings__mail__replyToEmail=no-reply@example.com
globalSettings__mail__smtp__host=smtp.example.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=false
globalSettings__mail__smtp__username=reply@example.com
globalSettings__mail__smtp__password=YOUR.PASSWORD
```

### Gmail 邮箱示例 <a href="#example-for-gmail" id="example-for-gmail"></a>

```systemd
globalSettings__mail__replyToEmail=yourname@gmail.com # 您的 Gmail 邮箱地址
globalSettings__mail__smtp__host=smtp.gmail.com
globalSettings__mail__smtp__port=465
globalSettings__mail__smtp__ssl=true
globalSettings__mail__smtp__username=yourname@gmail.com # 您的 Gmail 邮箱地址
globalSettings__mail__smtp__password=YOUR.PASSWORD # 如果您的 Google 账户开启了二次验证，这里必须使用应用专用密码
```

### [腾讯企业邮箱](https://exmail.qq.com/)示例 <a href="#example-for-qqmail" id="example-for-qqmail"></a>

```systemd
globalSettings__mail__replyToEmail=you@yourdomain.com # 您的企业邮箱的完整邮件地址
globalSettings__mail__smtp__host=smtp.exmail.qq.com
globalSettings__mail__smtp__port=465
globalSettings__mail__smtp__ssl=true
globalSettings__mail__smtp__username=you@yourdomain.com # 您的企业邮箱的完整邮件地址
globalSettings__mail__smtp__password=YOUR.PASSWORD # 您的企业邮箱密码（如已开启安全登陆则需要使用客户端专用密码)
```

**说明：**

* 将上面的电子邮件地址替换为您自己的腾讯企业邮箱地址
* `globalSettings__mail__smtp__host` 使用 `smtp.exmail.qq.com` 无效的话，尝试更换为 `hwsmtp.exmail.qq.com`

## 更新 Bitwarden <a href="#update-bitwarden" id="update-bitwarden"></a>

按顺序运行以下命令：

```shell
./bitwarden.sh updateself # 更新 bitwarden.sh 文件本身
./bitwarden.sh update # 更新 Bitwarden
```

等待完成。

{% hint style="info" %}
可以创建一个 cronjob 或计划任务以每周甚至每晚运行这些更新命令。这将自动使您的安装保持为最新。
{% endhint %}

## 备份和还原 <a href="#backup-and-restore" id="backup-and-restore"></a>

参考[官方帮助文档](https://help.ppgg.in/on-premises-hosting/backup-your-hosted-data)，或[使用 dropbox\_uploader.sh 脚本自动打包备份到 Dropbox](https://host.ppgg.in/vaultwarden/use#auto-backup-data)（推荐）。

## 使用系统管理员门户 <a href="#using-admin-portal" id="using-admin-portal"></a>

修改环境配置文件 `./bwdata/env/global.override.env` 中变量 `adminSettings__admins` 的值为可以访问管理门户的邮件地址（多个地址使用英文逗号分隔），以启用系统管理员门户。例如：

```systemd
adminSettings__admins=john@example.com,bill@gmail.com,tom@example.com
```

这些管理员电子邮件地址在您的 Bitwarden 安装中**不需要**是已注册的帐户。

如果您不想启用系统管理门户，将 `adminSettings__admins` 值保留为默认的空白值即可。

更多详细信息，请参考[此文](https://help.ppgg.in/on-premises-hosting/system-administrator-portal)。

{% hint style="warning" %}
要正常使用管理员门户，需要先配置好 SMTP。
{% endhint %}

{% hint style="info" %}
**如果您使用非默认的 HTTPS 端口，服务器版本为 1.37.1 的 Bitwarden 可能会有问题：**&#x5F53;访问 `https://vault.yourdomain.com:8443/admin` 时，它会自动跳转到 `https://vault.yourdomain.com/admin/login?returnUrl=%2Fadmin`导致无法访问。

解决方法就是在跳转地址中手动加入端口号后再访问。
{% endhint %}

## 删除 Bitwarden 安装 <a href="#remove-bitwarden-installation" id="remove-bitwarden-installation"></a>

删除比较简单。先停止 Bitwarden，然后删除 `bwdata` 文件夹即可。

```shell
./bitwarden.sh stop
```

## 设置 Fail2ban <a href="#setup-fail2ban" id="setup-fail2ban"></a>

设置[ Fail2ban](https://www.fail2ban.org/) 后，可以在您设置的 n 次错误登录后自动阻止登录的 IP 地址，防止攻击者暴力破解您的密码库登录，以增强您的 Bitwarden 的安全性。

{% hint style="danger" %}
为了使 Fail2ban 对 IP 拦截更准确，如果您的域名使用 [Cloudflare](https://www.cloudflare.com/) 解析，需要设置其代理状态为  `DNS only`，而不要设置为 `Proxied`。
{% endhint %}

{% hint style="info" %}
下面的 jail 文件中 的 `action =` 语句根据 CentOS 7 使用的是自带的 [Firewalld](https://firewalld.org/) 防火墙，如果使用 iptables，写法应有所不同。

参考资料：[bitwarden-fail2ban-libressl](https://github.com/yes-youcan/bitwarden-fail2ban-libressl)
{% endhint %}

这里以我的 [Vultr](https://www.vultr.com/?ref=7966491) 上的 CentOS 7 with Firewalld 服务器为例。

### 配置环境变量 <a href="#configure-environment-variables" id="configure-environment-variables"></a>

默认情况下，Bitwarden 日志文件的名称为`当前日期.txt`，需要在设置 Fail2ban 之前配置 Bitwarden 的环境变量开启滚动日志，以使日志文件名称更改为 `log.txt`。

编辑环境配置文件 `./bwdata/env/global.override.env` ，最下方添加一行环境变量：

```systemd
globalSettings__logRollBySizeLimit=1073741824 # 开启滚动日志并指定滚动日志文件的大小限制。这里我们设置为 1GB
```

重启 Bitwarden 使更改生效：

```shell
./bitwarden.sh restart
```

### 安装 Fail2ban <a href="#install-fail2ban" id="install-fail2ban"></a>

```shell
sudo yum install epel-release # 对于 CentOS 7 需要先安装 EPEL 库
sudo yum install fail2ban # 安装 Fail2Ban
```

将 Fail2ban 加入开机启动：

```shell
sudo systemctl enable fail2ban
```

启动 Fail2ban：

```shell
sudo systemctl start fail2ban
```

### 配置 Fail2ban <a href="#configure-fail2ban" id="configure-fail2ban"></a>

#### 创建 filter 文件 <a href="#create-filter-file" id="create-filter-file"></a>

对于 Bitwarden，我们直接使用 Fail2ban 自带的 `/etc/fail2ban/filter.d/bitwarden.conf` 文件，不需要做任何修改。

{% hint style="info" %}
如果您的 Fail2ban 不带此 bitwarden.conf 文件：

1、先创建文件：

```shell
vi /etc/fail2ban/filter.d/bitwarden.local
```

2、然后复制并粘帖如下内容：

```systemd
[INCLUDEshS]
before = common.conf

[Definition]
_daemon = Bitwarden-Identity
failregex = ^%(__prefix_line)s\s*\[(?:W(?:RN|arning)|Bit\.Core\.[^\]]+)\]\s+Failed login attempt(?:, 2FA invalid)?\. <ADDR>$
```

{% endhint %}

#### 创建 Jail 文件 <a href="#create-jail-file" id="create-jail-file"></a>

创建文件：

```shell
vi /etc/fail2ban/jail.d/bitwarden.local
```

复制并粘帖如下内容：

```systemd
[bitwarden]
enabled = true
filter = bitwarden
port = http,https
logpath = /root/bwdata/logs/identity/Identity/log.txt
action = iptables-allports[actname=bitwarden,name=bitwarden,protocol=all]
        iptables-allports[actname=bitwarden-docker,name=bitwarden-docker,protocol=all,chain=DOCKER-USER]
maxretry = 3
bantime = 43200
findtime = 3600
```

### 测试 Fail2ban <a href="#test-fail2ban" id="test-fail2ban"></a>

先打开文件监控：

```shell
sudo tail -f /var/log/fail2ban.log
```

然后尝试用错误的登录信息登录网页密码库，Fail2Ban 如果生效的话，将在 `fail2ban.log` 文件监控窗口显示相关的警告信息，类似于： `INFO [bitwarden] Found 110.238.14.224 - 2021-08-03 20:15:08`，当一定时间内达到设置的失败次数时：`NOTICE [bitwarden] Ban 110.238.14.224`，如下图：

![](https://1098296495-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MGNKm8ywtCheKTpUjpY%2F-MjiUDg0mkWx5lQHQpyQ%2F-MjiZK84TWfHuAsJNfr_%2Ffail2ban_bitwarden.png?alt=media\&token=87f9b180-5eb2-4b3f-b188-b0c11c841765)

同时查看系统的当前 iptables，在最下面会显示 f2b-bitwarden 封禁的 IP：

```shell
sudo iptables --list -n
```

如果您的 IP 被 ban，浏览器刷新时将无法再次打开网页密码库。

#### 解除被 ban 的 IP <a href="#unban-ip" id="unban-ip"></a>

```shell
sudo fail2ban-client set bitwarden unbanip xxx.xxx.xxx.xxx
```

#### Fail2ban 不起作用 <a href="#fail2ban-not-working" id="fail2ban-not-working"></a>

参看[故障 - Fail2ban 不起作用](https://host.ppgg.in/vaultwarden/troubleshoot#fail2ban-not-work)章节。

### Fail2ban 常用命令及参数解释 <a href="#fail2ban-common-commands" id="fail2ban-common-commands"></a>

Fail2ban 常用命令：

* `sudo systemctl start fail2ban` #启动 Fail2ban
* `sudo systemctl stop fail2ban` #停止 Fail2ban
* `sudo systemctl restart fail2ban` #重启 Fail2ban
* `sudo fail2ban-client ping` #检查 Fail2ban 是否正常运行（正常将显示 `pong`）

参数解释：

* `failregex = ^.*Invalid admin token\. IP: <ADDR>.*$` #查找日志记录中错误记录正则表达式
* `ignoreregex =` #忽略日志记录中错误记录正则表达式
* `filter = bitwarden` #对应的筛选器名称
* `action = iptables[name=bitwarden, port=443, protocol=tcp]` #动作参数
* `logpath = /root/bwdata/logs/identity/Identity/log.txt` #日志文件的路径
* `maxretry = 3` #IP 被 ban 前允许失败的次数
* `bantime = 43200` #IP 被 ban 的时长（秒），`-1` 表示永 ban
* `findtime = 3600` #此时长（秒）内达到 `maxretry` 次就 ban IP
* `ignoreip = xxx.xxx.xxx.xxxx` #不受限制的 IP