---
title: TiDB 白名单插件
summary: 了解如何部署和使用 TiDB 白名单插件。
---

# TiDB 白名单插件

TiDB 提供了白名单插件。使用该插件，你不需要在自己的业务层开发管理白名单功能，也不需要使用 MySQL 的用户功能逐个添加用户、管理权限，而是可以直接通过配置插件管控白名单，提高管理效率。

本文档介绍了如何使用白名单插件。

## 获取插件

请联系 PingCAP 销售获取插件安装包。

## 部署插件

你可以使用 TiDB Operator 或者 TiUP 部署白名单插件。

### 使用 TiDB Operator 部署插件

配置 TidbCluster CR。

```yaml
  tidb:
    additionalContainers:
    - command:
      - sh
      - -c
      - touch /var/log/tidb/tidb-whitelist.log; tail -n0 -F /var/log/tidb/tidb-whitelist.log;
      image: busybox:1.26.2
      imagePullPolicy: IfNotPresent
      name: whitelistlog
      resources:
        limits:
          cpu: 100m
          memory: 50Mi
        requests:
          cpu: 20m
          memory: 5Mi
      terminationMessagePath: /dev/termination-log
      terminationMessagePolicy: File
      volumeMounts:
      - mountPath: /var/log/tidb
        name: slowlog
    baseImage: <your_private_docker_hub_username>/tidb-ent:v5.4.0
    plugins:
    - whitelist-1
```

### 使用 TiUP 部署插件

#### 在已部署集群上追加插件

1. 在所有目标服务器建立文件夹。

    ```shell
    tiup cluster exec cluster_name --command "mkdir {{.DeployDir}}/plugin" -R tidb
    ```

2. 传输插件到所有目标服务器。

    ```shell
    tiup cluster push cluster_name ~/Download/whitelist-1.so {{.DeployDir}}/plugin/whitelist-1.so -R tidb
    ```

3. 修改 TiDB 配置。

    ```shell
    tiup cluster edit-config cluster_name
    ```

    在每个 TiDB 节点下的 config 字段中，配置 plugin.dir 为对应**绝对路径**，plugin.load 为插件名。

    ```yaml
    tidb_servers:
   -  host: 172.16.7.213
       ssh_port: 22
       port: 4000
       status_port: 10080
       deploy_dir: /tidb-deploy/tidb-4000
       log_dir: /tidb-deploy/tidb-4000/log
       arch: amd64
      os: linux
       config:
           plugin.dir: /tidb-deploy/tidb-4000/plugin
           plugin.load: whitelist-1
    ```

4. 滚动重启所有 TiDB 节点。

    ```shell
    tiup cluster reload cluster_name -R tidb
    ```

建议：

* 步骤 3 中，如果所有节点部署路径完全相同，可直接在 server_configs.tidb 中进行全局配置，避免手动修改每一个节点。如果路径不完全相同，可以修改步骤 1、2 中 plugin 的路径为某一相同路径。
* 如果不是所有 TiDB 节点都要部署插件， 通过 -N 参数来指定节点（tiup cluster display 显示的 ID）。

#### 安装时部署

安装时部署与“在已部署集群上追加插件”的操作步骤相似：在部署前的拓扑文件中配置好 plugin.load 和 plugin.dir，在启动集群前执行 `tiup cluster exec` 和 `tiup cluster push`。

#### 扩容

按照常规操作正常扩容节点，然后参考“在已部署集群上追加插件”的操作步骤，通过 -N 参数指定刚扩容的节点。

请注意，你需要在扩容进行期间将插件安装文件（如上面例子中的 whitelist-1.so）上传到目标服务器，而且要确保在扩容结束之前传完，否则扩容会报错。

如果扩容报错，你可以执行以下操作重新安装插件：

1. 重新进行扩容。
2. 在扩容完成后上传插件安装文件。
3. 执行 `tiup cluster start cluster_name` 命令重启。

#### 升级集群

1. 删除老插件。

    ```shell
    tiup cluster exec cluster_name --command "rm {{.DeployDir}}/plugin/whitelist-1.so" -R tidb
    ```

2. 传输新插件到所有目标服务器。为了避免修改配置，使用相同名称。

    ```shell
    tiup cluster push cluster_name ~/Download/whitelist-1_new.so {{.DeployDir}}/plugin/whitelist-1.so -R tidb
    ```

    **说明：**域名不能包含 “-” （如 tidb-server1），否则该命令会执行失败。

3. 升级集群。

    ```shell
    tiup cluster upgrade cluster_name version
    ```

## 查看状态

使用 MySQL 的 `show plugins` 命令，可以查看当前插件加载和启用状态信息：

* Name: 插件名称
* Status: 插件状态, 由加载状态 (uninitialized, ready) 和启用状态 (enable, disable) 组成
* Type: 插件类型
* Library: 插件二进制文件位置
* Version: 插件版本

![Show Plugins](media/plugin-allowlist-show.png)

## 启用和禁用插件

开启白名单以后，TiDB 会根据用户 IP 进行过滤，只有属于白名单的 IP 才允许登录。启用或禁用命令在可以在任意一个 TiDB 节点执行。执行成功后，会作用于集群中所有 TiDB 节点。

如不希望过滤 IP，可以禁用白名单插件。

要禁用和重启用白名单插件，分别执行以下相应的 admin plugins 命令即可：

```shell
mysql> admin plugins disable whitelist;
mysql> admin plugins enable whitelist;
```

![Disable Plugins](media/plugin-allowlist-disable.png)

你可以使用 MySQL 的 `show plugins` 命令查看插件的启用状态信息。

## 使用和验证插件

白名单插件启用后，TiDB 会从 `mysql.whitelist` 系统表读取白名单信息。

![Plugin Allowlist](media/plugin-allowlist.png)

白名单表的 list 字段格式为一个字符串，以单个英文逗号 “,” 为分隔符，连接一串的 IP 网段。IP 网段以 CIDR 格式表示，比如 192.0.2.1/24。具体使用方法，请参考 [Go 的 ParseCIDR 函数](https://godoc.org/net#example-ParseCIDR)。

白名单插件一般配合前端 Web 使用。手动的验证操作如下：

1. 添加一条白名单记录，允许 192.0.2.0 网段和 127.0.0.0 网段的 IP 访问服务器：

    ```shell
    mysql> insert into mysql.whitelist (name, list) values ('default', '192.0.2.1/24,127.0.0.1/24');
    Query OK, 1 row affected (0.04 sec)
    ```

2. 配置生效后，从非白名单的 IP 机器去连接 TiDB 的时候会报错：

    ```shell
    bin git:(master) mysql -h zenlife.tk -P 4000 -u root
    ERROR 2013 (HY000): Lost connection to MySQL server at 'reading initial communication packet', system error: 0
    ```