Meowlnir

https://docs.mau.fi/meowlnir/
Admin
Meowlnir is a moderation tool and application service for Matrix homeservers that watches policy...
Tokens:7,905
Snippets:58
Trust Score:7.4
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Generate example config with docker run

Source: https://docs.mau.fi/meowlnir/setup-docker.html

Runs the Meowlnir container with the -e flag to generate an example config. The -v flag mounts the current directory to /data, and the :z suffix is for SELinux. Replace <version> with the desired version tag.

```bash
docker run --rm -v `pwd`:/data:z dock.mau.dev/maunium/meowlnir:<version> /usr/bin/meowlnir -e
```

--------------------------------

### Run Meowlnir container

Source: https://docs.mau.fi/meowlnir/setup-docker.html

Starts the Meowlnir container with restart policy unless-stopped and mounts the current directory to /data. Add --network=synapsenet or -p 29339:29339 for networking depending on your setup.

```bash
docker run --restart unless-stopped -v `pwd`:/data:z dock.mau.dev/maunium/meowlnir:<version>
```

--------------------------------

### docker-compose.yml for Meowlnir

Source: https://docs.mau.fi/meowlnir/setup-docker.html

Example docker-compose.yml for running Meowlnir. Includes commented sections for port exposure and networking with Synapse. Adjust the volumes section if using an existing compose file.

```yaml
version: "3.7"

services:
  meowlnir:
    container_name: meowlnir
    image: dock.mau.dev/maunium/meowlnir:<version>
    restart: unless-stopped
    volumes:
    - .:/data

    # If you put the service above in the same docker-compose as the homeserver,
    # ignore the parts below. Otherwise, see below for configuring networking.

    # If synapse is running outside of docker, you'll need to expose the port.
    # Note that in most cases you should either run everything inside docker
    # or everything outside docker, rather than mixing docker things with
    # non-docker things.
    #ports:
    #- "29339:29339"
    # You'll also probably want this so Meowlnir can reach Synapse directly
    # using something like `http://host.docker.internal:8008` as the address:
    #extra_hosts:
    #- "host.docker.internal:host-gateway"

    # If synapse is in a different network, then add this container to that network.
    #networks:
    #- synapsenet
# This is also a part of the networks thing above
#networks:
#  synapsenet:
#    external:
#      name: synapsenet
```

--------------------------------

### Create a bot with PUT /_meowlnir/v1/bot/{localpart}

Source: https://docs.mau.fi/meowlnir/bot-create.html

Creates a bot with the localpart 'abuse', displayname 'Administrator', and the specified avatar URL. This example copies matrix.org's admin bot.

```bash
curl -H "$AUTH" https://meowlnir.example.com/_meowlnir/v1/bot/abuse -XPUT -d '{"displayname": "Administrator", "avatar_url": "mxc://matrix.org/NZGChxcCXbBvgkCNZTLXlpux"}'
```

--------------------------------

### GET /_meowlnir/v1/bots

Source: https://docs.mau.fi/meowlnir/bot-create.html

Lists all bots managed by Meowlnir.

```APIDOC
## GET /_meowlnir/v1/bots

### Description
List all bots.

### Method
GET

### Endpoint
/_meowlnir/v1/bots

### Authentication
Requires `Authorization: Bearer $MANAGEMENT_SECRET` header.

### Response
#### Success Response (200)
- **body** (array) - List of bots.

#### Response Example
```json
[]
```
```

--------------------------------

### Define a management room with PUT /_meowlnir/v1/management_room/{roomID}

Source: https://docs.mau.fi/meowlnir/bot-create.html

Defines a room as a management room for the specified bot. After defining the room, you can invite the bot and it should accept the invite.

```bash
curl -H "$AUTH" -X PUT 'https://meowlnir.example.com/_meowlnir/v1/management_room/!randomroomid:example.com' -d '{"bot_username": "abuse"}'
```

--------------------------------

### Subscribe to policy lists with fi.mau.meowlnir.watched_lists

Source: https://docs.mau.fi/meowlnir/bot-config.html

Send this state event to subscribe to policy lists. The state key must be empty and the content must have a `lists` key containing objects with `room_id`, `shortcode`, and `name`. Extra flags like `auto_unban`, `auto_suspend`, and `dont_apply` are optional. After sending, Meowlnir confirms success with a message; if no message appears, the event was likely malformed.

```json
{
    "lists": [
        {
            "auto_unban": true,
            "auto_suspend": true,
            "name": "CME bans",
            "room_id": "!fTjMjIzNKEsFlUIiru:neko.dev",
            "shortcode": "cme"
        },
        {
            "name": "Cat's Active Threats",
            "room_id": "!QJKZNWnsItkUuthamp:feline.support",
            "shortcode": "cat"
        },
        {
            "auto_unban": true,
            "dont_apply": true,
            "name": "matrix.org coc",
            "room_id": "!WuBtumawCeOGEieRrp:matrix.org",
            "shortcode": "morg-coc"
        },
        {
            "auto_unban": true,
            "dont_apply": true,
            "name": "matrix.org tos",
            "room_id": "!tUPwPPmVTaiKXMiijj:matrix.org",
            "shortcode": "morg-tos"
        }
    ]
}
```

--------------------------------

### PUT /_meowlnir/v1/bot/{localpart}

Source: https://docs.mau.fi/meowlnir/bot-create.html

Creates a new bot with the specified localpart. Optionally sets display name and avatar.

```APIDOC
## PUT /_meowlnir/v1/bot/{localpart}

### Description
Create a bot with the given localpart (username).

### Method
PUT

### Endpoint
/_meowlnir/v1/bot/{localpart}

### Authentication
Requires `Authorization: Bearer $MANAGEMENT_SECRET` header.

### Parameters
#### Path Parameters
- **localpart** (string) - Required - The localpart (username) of the bot to create.

#### Request Body
- **displayname** (string) - Optional - Display name for the bot.
- **avatar_url** (string) - Optional - MXC URI for the bot's avatar.

### Request Example
```json
{
  "displayname": "Administrator",
  "avatar_url": "mxc://matrix.org/NZGChxcCXbBvgkCNZTLXlpux"
}
```

### Response
#### Success Response (200)
- **body** (object) - Created bot information.

#### Response Example
```json
{}
```
```

--------------------------------

### Generate cross-signing keys with POST /_meowlnir/v1/bot/{localpart}/verify

Source: https://docs.mau.fi/meowlnir/bot-create.html

Generates cross-signing keys for the bot and returns the recovery key. Use this if the bot user didn't have encryption before. Make sure to save the recovery key.

```bash
curl -H "$AUTH" https://meowlnir.example.com/_meowlnir/v1/bot/abuse/verify -d '{"generate": true}'
```

--------------------------------

### Protect rooms with fi.mau.meowlnir.protected_rooms

Source: https://docs.mau.fi/meowlnir/bot-config.html

Send this state event to list rooms the bot should protect. The state key must be empty and the content is a `rooms` key containing a list of room IDs. After adding rooms, invite the bot to the room or use the `!join` command.

```json
{
    "rooms": [
        "!randomid:example.com",
        "!anotherrandomid:example.com"
    ]
}
```

--------------------------------

### Appservice registration file for Meowlnir

Source: https://docs.mau.fi/meowlnir/config.html

YAML registration file for Meowlnir appservice. Must match the Meowlnir config exactly. Includes required namespaces and encryption-related flags.

```yaml
# ID and tokens must be exactly the same as in the Meowlnir config.
id: ...
as_token: ...
hs_token: ...
# The URL where the homeserver can reach Meowlnir.
url: http://localhost:29339
# This doesn't matter, just needs to be unique.
sender_localpart: any random string here
# Meowlnir will not handle ratelimits, so this must be false.
rate_limited: false
# Meowlnir uses MSC3202, MSC4190 and MSC4203 for encryption,
# so they must be enabled if you want encryption support.
org.matrix.msc3202: true
io.element.msc4190: true
# push_ephemeral is the old name of receive_ephemeral, as Synapse hasn't stabilized MSC2409 support yet.
# Enabling 2409/receive_ephemeral is required for MSC4203, but is not otherwise used by Meowlnir.
de.sorunome.msc2409.push_ephemeral: true
receive_ephemeral: true
# Add the bots you want here. If you only want one bot, a static regex is enough.
# Multiple bots are supported too and can be dynamically added if you set a non-static regex (e.g. `@moderation_.+:example\.com`)
namespaces:
  users:
  - regex: '@abuse:example\.com'
    exclusive: true
```

--------------------------------

### Add index for efficient event lookup

Source: https://docs.mau.fi/meowlnir/config.html

SQL to create an index on the events table to improve Meowlnir's direct database reads for finding events to redact and soft-failed events.

```sql
CREATE INDEX meowlnir_event_sender_idx ON events (room_id, sender);
```

--------------------------------

### Configure synapse-http-antispam for Meowlnir invite blocking

Source: https://docs.mau.fi/meowlnir/invite-blocking.html

Configure the synapse-http-antispam module to block invites based on Meowlnir policy lists. Set base_url to the Meowlnir antispam endpoint with the management room ID, and authorization to the antispam.secret value. The user_may_invite callback blocks invites from banned users, while user_may_join_room tracks accepted invites and, if auto_reject_invites_token is set, automatically rejects pending invites from banned users.

```yaml
modules:
  - module: synapse_http_antispam.HTTPAntispam
    config:
      base_url: http://localhost:29339/_meowlnir/antispam/<management room ID>
      authorization: <value of antispam.secret>
      enabled_callbacks:
      - user_may_invite
      - user_may_join_room
      async:
        user_may_join_room: true
```

--------------------------------

### Create read-only Synapse database user for Meowlnir

Source: https://docs.mau.fi/meowlnir/config.html

SQL statements to create a read-only user for Meowlnir's optional direct database access. Grants CONNECT, USAGE, and SELECT on all tables in the public schema.

```sql
CREATE USER meowlnir WITH PASSWORD '...';
GRANT CONNECT ON DATABASE synapse TO meowlnir;
GRANT USAGE ON SCHEMA public TO meowlnir;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO meowlnir;
```

--------------------------------

### Enable Synapse experimental features for Meowlnir encryption

Source: https://docs.mau.fi/meowlnir/config.html

YAML configuration for Synapse's experimental_features to support Meowlnir's encryption features (MSC3202, MSC2409, MSC4203).

```yaml
experimental_features:
  # Actually MSC4203, but it was previously a part of MSC2409
  msc2409_to_device_messages_enabled: true
  # MSC3202 has two parts, both need to be enabled
  msc3202_device_masquerading: true
  msc3202_transaction_extensions: true
```

--------------------------------

### PUT /_meowlnir/v1/management_room/{roomID}

Source: https://docs.mau.fi/meowlnir/bot-create.html

Defines a room as a management room for a specified bot.

```APIDOC
## PUT /_meowlnir/v1/management_room/{roomID}

### Description
Define a room as a management room for a bot.

### Method
PUT

### Endpoint
/_meowlnir/v1/management_room/{roomID}

### Authentication
Requires `Authorization: Bearer $MANAGEMENT_SECRET` header.

### Parameters
#### Path Parameters
- **roomID** (string) - Required - The room ID to define as a management room.

#### Request Body
- **bot_username** (string) - Required - The username of the bot to associate with this management room.

### Request Example
```json
{
  "bot_username": "abuse"
}
```

### Response
#### Success Response (200)
- **body** (object) - Confirmation of the management room definition.

#### Response Example
```json
{}
```
```

--------------------------------

### Verify bot with recovery key

Source: https://docs.mau.fi/meowlnir/bot-create.html

Verifies the bot using an existing recovery key. Use this if the user already has cross-signing set up.

```bash
curl -H "$AUTH" https://meowlnir.example.com/_meowlnir/v1/bot/abuse/verify -d '{"recovery_key": "EsT* ****..."}'
```

--------------------------------

### POST /_meowlnir/v1/bot/{localpart}/verify

Source: https://docs.mau.fi/meowlnir/bot-create.html

Verifies a bot's device for encryption. Can generate cross-signing keys or use an existing recovery key.

```APIDOC
## POST /_meowlnir/v1/bot/{localpart}/verify

### Description
Cross-sign a bot's device. Can generate cross-signing keys or use an existing recovery key.

### Method
POST

### Endpoint
/_meowlnir/v1/bot/{localpart}/verify

### Authentication
Requires `Authorization: Bearer $MANAGEMENT_SECRET` header.

### Parameters
#### Path Parameters
- **localpart** (string) - Required - The localpart (username) of the bot to verify.

#### Request Body
- **generate** (boolean) - Optional - If true, generate cross-signing keys and return a recovery key.
- **recovery_key** (string) - Optional - Recovery key to use for verification.

### Request Example
```json
{
  "generate": true
}
```

### Response
#### Success Response (200)
- **recovery_key** (string) - The recovery key if `generate` was true.

#### Response Example
```json
{
  "recovery_key": "EsT* ****..."
}
```
```

--------------------------------

### Caddy reverse proxy configuration for Meowlnir endpoints

Source: https://docs.mau.fi/meowlnir/reverse-proxy.html

Caddy configuration for routing Meowlnir endpoints. The first block handles report interception endpoints by proxying them to localhost:29339, and the second block handles the policy server endpoint for MSC4284.

```caddy
matrix-client.example.com {
    @reporting {
        path /_matrix/client/v3/rooms/*/report/* /_matrix/client/v3/rooms/*/report /_matrix/client/v3/users/*/report
    }
    handle @reporting {
        reverse_proxy http://localhost:29339
    }
}

matrix-federation.example.com {
    handle /_matrix/policy/* {
        reverse_proxy http://localhost:29339
    }
}
```

--------------------------------

### Set AUTH header for Meowlnir API

Source: https://docs.mau.fi/meowlnir/bot-create.html

Sets the AUTH environment variable to the Authorization header using the MANAGEMENT_SECRET from the config. This is used to authenticate with the Meowlnir API.

```bash
export AUTH="Authorization: Bearer $MANAGEMENT_SECRET"
```

--------------------------------

### Mount subdirectory for existing docker-compose

Source: https://docs.mau.fi/meowlnir/setup-docker.html

Adjust the volumes section to mount a subdirectory instead of the current directory as the data directory when using an existing docker-compose file.

```yaml
volumes:
- ./meowlnir:/data
```
Tokens:
Raw