黑名單
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
