kopia lustrzana https://github.com/Yakifo/amqtt
140 wiersze
4.0 KiB
Markdown
140 wiersze
4.0 KiB
Markdown
# Existing Plugins
|
|
|
|
With the aMQTT Broker plugins framework, one can add additional functionality without
|
|
having to rewrite core logic. Plugins loaded by default are specified in `pyproject.toml`:
|
|
|
|
```yaml
|
|
--8<-- "pyproject.toml:included"
|
|
```
|
|
|
|
## auth_anonymous (Auth Plugin)
|
|
|
|
`amqtt.plugins.authentication:AnonymousAuthPlugin`
|
|
|
|
|
|
**Configuration**
|
|
|
|
```yaml
|
|
auth:
|
|
plugins:
|
|
- auth_anonymous
|
|
allow-anonymous: true # if false, providing a username will allow access
|
|
|
|
```
|
|
|
|
!!! danger
|
|
even if `allow-anonymous` is set to `false`, the plugin will still allow access if a username is provided by the client
|
|
|
|
|
|
## auth_file (Auth Plugin)
|
|
|
|
`amqtt.plugins.authentication:FileAuthPlugin`
|
|
|
|
clients are authorized by providing username and password, compared against file
|
|
|
|
**Configuration**
|
|
|
|
```yaml
|
|
|
|
auth:
|
|
plugins:
|
|
- auth_file
|
|
password-file: /path/to/password_file
|
|
|
|
```
|
|
|
|
**File Format**
|
|
|
|
The file includes `username:password` pairs, one per line.
|
|
|
|
The password should be encoded using sha-512 with `mkpasswd -m sha-512` or:
|
|
|
|
```python
|
|
import sys
|
|
from getpass import getpass
|
|
from passlib.hash import sha512_crypt
|
|
|
|
passwd = input() if not sys.stdin.isatty() else getpass()
|
|
print(sha512_crypt.hash(passwd))
|
|
```
|
|
|
|
## Taboo (Topic Plugin)
|
|
|
|
`amqtt.plugins.topic_checking:TopicTabooPlugin`
|
|
|
|
Prevents using topics named: `prohibited`, `top-secret`, and `data/classified`
|
|
|
|
**Configuration**
|
|
|
|
```yaml
|
|
topic-check:
|
|
enabled: true
|
|
plugins:
|
|
- topic_taboo
|
|
```
|
|
|
|
## ACL (Topic Plugin)
|
|
|
|
`amqtt.plugins.topic_checking:TopicAccessControlListPlugin`
|
|
|
|
**Configuration**
|
|
|
|
- `acl` *(list)*: determines subscription access; if `publish-acl` is not specified, determine both publish and subscription access.
|
|
The list should be a key-value pair, where:
|
|
`<username>:[<topic1>, <topic2>, ...]` *(string, list[string])*: username of the client followed by a list of allowed topics (wildcards are supported: `#`, `+`).
|
|
|
|
|
|
- `publish-acl` *(list)*: determines publish access. This parameter defines the list of access control rules; each item is a key-value pair, where:
|
|
`<username>:[<topic1>, <topic2>, ...]` *(string, list[string])*: username of the client followed by a list of allowed topics (wildcards are supported: `#`, `+`).
|
|
|
|
!!! info "Reserved usernames"
|
|
|
|
- The username `admin` is allowed access to all topics.
|
|
- The username `anonymous` will control allowed topics, if using the `auth_anonymous` plugin.
|
|
|
|
```yaml
|
|
topic-check:
|
|
enabled: true
|
|
plugins:
|
|
- topic_acl
|
|
publish-acl:
|
|
- username: ["list", "of", "allowed", "topics", "for", "publishing"]
|
|
- .
|
|
acl:
|
|
- username: ["list", "of", "allowed", "topics", "for", "subscribing"]
|
|
- .
|
|
```
|
|
|
|
## Plugin: $SYS
|
|
|
|
`amqtt.plugins.sys.broker:BrokerSysPlugin`
|
|
|
|
Publishes, on a periodic basis, statistics about the broker
|
|
|
|
**Configuration**
|
|
|
|
- `sys_interval` - int, seconds between updates
|
|
|
|
**Supported Topics**
|
|
|
|
- `$SYS/broker/version` - payload: `str`
|
|
- `$SYS/broker/load/bytes/received` - payload: `int`
|
|
- `$SYS/broker/load/bytes/sent` - payload: `int`
|
|
- `$SYS/broker/messages/received` - payload: `int`
|
|
- `$SYS/broker/messages/sent` - payload: `int`
|
|
- `$SYS/broker/time` - payload: `int` (current time, epoch seconds)
|
|
- `$SYS/broker/uptime` - payload: `int` (seconds since broker start)
|
|
- `$SYS/broker/uptime/formatted` - payload: `str` (start time of broker in UTC)
|
|
- `$SYS/broker/clients/connected` - payload: `int` (current number of connected clients)
|
|
- `$SYS/broker/clients/disconnected` - payload: `int` (number of clients that have disconnected)
|
|
- `$SYS/broker/clients/maximum` - payload: `int`
|
|
- `$SYS/broker/clients/total` - payload: `int`
|
|
- `$SYS/broker/messages/inflight` - payload: `int`
|
|
- `$SYS/broker/messages/inflight/in` - payload: `int`
|
|
- `$SYS/broker/messages/inflight/out` - payload: `int`
|
|
- `$SYS/broker/messages/inflight/stored` - payload: `int`
|
|
- `$SYS/broker/messages/publish/received` - payload: `int`
|
|
- `$SYS/broker/messages/publish/sent` - payload: `int`
|
|
- `$SYS/broker/messages/retained/count` - payload: `int`
|
|
- `$SYS/broker/messages/subscriptions/count` - payload: `int`
|