EMQX用户指南- 黑名单

黑名单

EMQ X 为用户提供了黑名单功能，用户可以通过相关的 HTTP API 将指定客户端加入黑名单以拒绝该客户端访问，除了客户端标识符以外，还支持直接封禁用户名甚至 IP 地址。

黑名单HTTP API

GET /api/v4/banned

获取黑名单

Query String Parameters:

同 /api/v4/clients。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array	由对象构成的数组，对象中的字段与 POST 方法中的 Request Body 相同
meta	Object	同 /api/v4/clients

Examples:

获取黑名单列表:

$ curl -i --basic -u admin:public -vX GET "http://localhost:8081/api/v4/banned"

{"meta":{"page":1,"limit":10000,"count":1},"data":[{"who":"example","until":1582265833,"reason":"undefined","by":"user","at":1582265533,"as":"clientid"}],"code":0}

POST /api/v4/banned

将对象添加至黑名单

Parameters (json):

Name	Type	Required	Default	Description
who	String	Required		添加至黑名单的对象，可以是客户端标识符、用户名和 IP 地址
as	String	Required		用于区分黑名单对象类型，可以是 clientid，username，peerhost
by	String	Optional	user	指示该对象被谁添加至黑名单
at	Integer	Optional	当前系统时间	添加至黑名单的时间，单位：秒
until	Integer	Optional	当前系统时间 + 5 分钟	何时从黑名单中解除，单位：秒

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object	与传入的 Request Body 相同

Examples:

将 client 添加到黑名单:

$ curl -i --basic -u admin:public -vX POST "http://localhost:8081/api/v4/banned" -d '{"who":"example","as":"clientid"}'

{"data":{"who":"example","as":"clientid"},"code":0}

DELETE /api/v4/banned/{as}/{who}

将对象从黑名单中删除

Parameters: 无

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
message	String	仅在发生错误时返回，用于提供更详细的错误信息

Examples:

将 client 从黑名单中移除:

$ curl -i --basic -u admin:public -X DELETE "http://localhost:8081/api/v4/banned/clientid/example"

{"code":0}

黑名单系统默认功能

在黑名单功能的基础上，EMQ X 支持自动封禁那些被检测到短时间内频繁登录的客户端，并且在一段时间内拒绝这些客户端的登录，以避免此类客户端过多占用服务器资源而影响其他客户端的正常使用。

需要注意的是，自动封禁功能只封禁客户端标识符，并不封禁用户名和 IP 地址，即该机器只要更换客户端标识符就能够继续登录。

此功能默认关闭，用户可以在 emqx.conf 配置文件中将 enable_flapping_detect 配置项设为 on 以启用此功能。

zone.external.enable_flapping_detect = off

用户可以为此功能调整触发阈值和封禁时长，对应配置项如下：

flapping_detect_policy = 30, 1m, 5m

此配置项的值以 , 分隔，依次表示客户端离线次数，检测的时间范围以及封禁时长，因此上述默认配置即表示如果客户端在 1 分钟内离线次数达到 30 次，那么该客户端使用的客户端标识符将被封禁 5 分钟。当然你也可以使用其他诸如秒、小时在内的时间单位。

附录

duration数据类型的几种单位

duration 用于指定那些固定的时间间隔，你可以使用以下时间单位：

• f - fortnight
• w - week
• d - day
• h - hour
• m - minute
• s - second
• ms - millisecond