amqtt/docs/packaged_plugins.md

# Existing Plugins

With the aMQTT plugins framework, one can add additional functionality without
having to rewrite core logic in the broker or client. Plugins can be loaded and configured using
the `plugins` section of the config file (or parameter passed to the class). 


## Broker

By default, `EventLoggerPlugin`, `PacketLoggerPlugin`, `AnonymousAuthPlugin` and `BrokerSysPlugin` are activated
and configured for the broker:

```yaml
--8<-- "amqtt/scripts/default_broker.yaml"
```


??? warning "Loading plugins from EntryPoints in `pyproject.toml` has been deprecated"

    Previously, all plugins were loaded from EntryPoints:

    ```toml
    --8<-- "pyproject.toml:included"
    ```

    But the same 4 plugins were activated in the previous default config:

    ```yaml
    --8<-- "samples/legacy.yaml"
    ```

## Client

By default, the `PacketLoggerPlugin` is  activated  and configured for the client:

```yaml
--8<-- "amqtt/scripts/default_client.yaml"
```

## Plugins

### Anonymous (Auth Plugin)

`amqtt.plugins.authentication.AnonymousAuthPlugin`

**Configuration**

```yaml
plugins:
  - ...
  - amqtt.plugins.authentication.AnonymousAuthPlugin:
      allow_anonymous: false 
  - ...

```

!!! danger
    even if `allow_anonymous` is set to `false`, the plugin will still allow access if a username is provided by the client


??? warning "EntryPoint-style configuration is deprecated"

    ```yaml
    auth:
      plugins:
        - auth_anonymous
      allow-anonymous: true # if false, providing a username will allow access
    
    ```

### Password File (Auth Plugin)

`amqtt.plugins.authentication.FileAuthPlugin`

clients are authorized by providing username and password, compared against file

**Configuration**

```yaml
plugins:
  - ...
  - amqtt.plugins.authentication.FileAuthPlugin:
      password_file: /path/to/password_file 
  - ...
```

??? warning "EntryPoint-style configuration is deprecated"
    ```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
plugins:
  - ...
  - amqtt.plugins.topic_checking.TopicTabooPlugin:
  - ...
```

??? warning "EntryPoint-style configuration is deprecated"

    ```yaml
    topic-check:
      enabled: true
      plugins:
        - topic_taboo
    ```

### ACL (Topic Plugin)

`amqtt.plugins.topic_checking.TopicAccessControlListPlugin`

**Configuration**

- `acl` *(mapping)*: 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` *(mapping)*: 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
plugins:
  - ...
  - amqtt.plugins.topic_checking.TopicAccessControlListPlugin:
      publish_acl:
        - username: ["list", "of", "allowed", "topics", "for", "publishing"]
      acl:
        - username: ["list", "of", "allowed", "topics", "for", "subscribing"]
  - ...
```

??? warning "EntryPoint-style configuration is deprecated"
    ```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"]
        - .
    ```

### $SYS topics

`amqtt.plugins.sys.broker.BrokerSysPlugin`

Publishes, on a periodic basis, statistics about the broker

**Configuration**

- `sys_interval` - int, seconds between updates
```yaml
plugins:
  - ...
  - amqtt.plugins.sys.broker.BrokerSysPlugin:
      sys_interval: 20  # int, seconds between updates 
  - ...
```

**Supported Topics**

- `$SYS/broker/version` *(string)*
- `$SYS/broker/load/bytes/received` *(int)*
- `$SYS/broker/load/bytes/sent` *(int)*
- `$SYS/broker/messages/received`  *(int)*
- `$SYS/broker/messages/sent`  *(int)*
- `$SYS/broker/time`  *(int, current time in epoch seconds)*
- `$SYS/broker/uptime` *(int, seconds since broker start)*
- `$SYS/broker/uptime/formatted` *(string, start time of broker in UTC)*
- `$SYS/broker/clients/connected` *(int, number of currently connected clients)*
- `$SYS/broker/clients/disconnected` *(int, number of clients that have disconnected)*
- `$SYS/broker/clients/maximum` *(int, maximum number of clients connected)*
- `$SYS/broker/clients/total` *(int)*
- `$SYS/broker/messages/inflight` *(int)*
- `$SYS/broker/messages/inflight/in` *(int)*
- `$SYS/broker/messages/inflight/out` *(int)*
- `$SYS/broker/messages/inflight/stored` *(int)*
- `$SYS/broker/messages/publish/received` *(int)*
- `$SYS/broker/messages/publish/sent` *(int)*
- `$SYS/broker/messages/retained/count` *(int)*
- `$SYS/broker/messages/subscriptions/count` *(int)*
- `$SYS/broker/heap/size` *(float, MB)*
- `$SYS/broker/heap/maximum` *(float, MB)*
- `$SYS/broker/cpu/percent` *(float, %)*
- `$SYS/broker/cpu/maximum` *(float, %)*


### Event Logger

`amqtt.plugins.logging_amqtt.EventLoggerPlugin`

This plugin issues log messages when [broker and mqtt events](custom_plugins.md#events) are triggered:

- info level messages for `client connected` and `client disconnected`
- debug level for all others


### Packet Logger

`amqtt.plugins.logging_amqtt.PacketLoggerPlugin`

This plugin issues debug-level messages for [mqtt events](custom_plugins.md#client-and-broker): `on_mqtt_packet_sent`
and `on_mqtt_packet_received`.