Matrix-Mirrors/mjolnir
1
0
Fork 0
mirror of https://github.com/matrix-org/mjolnir.git synced 2024-10-01 01:36:06 -04:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation (#277)

Browse Source 
* improve documentation

* incorperate documentation of configuration into sample file
This commit is contained in:
Jonathan de Jong 2022-05-20 13:19:26 +02:00 committed by GitHub
parent bcc3405e51
commit bf7f1318af
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 314 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
README.md
View File

@ -16,57 +16,13 @@ directory changes, room alias transfers, account deactivation, room shutdown, an
A Synapse module is also available to apply the same rulesets the bot uses across an entire A Synapse module is also available to apply the same rulesets the bot uses across an entire
homeserver. homeserver.
## Bot configuration ## Setting up
It is recommended to use [Pantalaimon](https://github.com/matrix-org/pantalaimon) so your See the [setup documentation](docs/setup.md) for first-time setup documentation.
management room can be encrypted. This also applies if you are looking to moderate an encrypted
room.
If you aren't using encrypted rooms anywhere, get an access token by opening Riot in an See the [configuration sample with documentation](config/default.yaml) for detailed information about Mjolnir's configuration.
incognito/private window and log in as the bot. From the Help & Support tab in settings there
is an access token field - copy and paste that into your config. Most importantly: do not log
out and instead just close the window. Logging out will make the token you just copied useless.
**Note**: Mjolnir expects to be free of rate limiting - see [Synapse #6286](https://github.com/matrix-org/synapse/issues/6286) See the [synapse module documentation](docs/synapse_module.md) for information on how to setup Mjolnir's accompanying Synapse Module.
for information on how to achieve this.
**Note**: To deactivate users, move aliases, shutdown rooms, etc Mjolnir will need to be a server
admin.
## Docker installation (preferred)
Mjolnir is on Docker Hub as [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir)
but can be built yourself with `docker build -t mjolnir .`.
```bash
git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir
# Copy and edit the config. It is not recommended to change the data path.
mkdir -p /etc/mjolnir/config
cp config/default.yaml /etc/mjolnir/config/production.yaml
nano /etc/mjolnir/config/production.yaml
docker run --rm -it -v /etc/mjolnir:/data matrixdotorg/mjolnir:latest
```
## Build it (alternative installation)
This bot requires `yarn` and Node 14.
```bash
git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir
yarn install
yarn build
# Copy and edit the config. It *is* recommended to change the data path.
cp config/default.yaml config/development.yaml
nano config/development.yaml
node lib/index.js
```
## Quickstart guide ## Quickstart guide
@ -82,73 +38,6 @@ set up:
3. Review the [Moderator's Guide](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md). 3. Review the [Moderator's Guide](https://github.com/matrix-org/mjolnir/blob/main/docs/moderators.md).
4. Review `!mjolnir help` to see what else the bot can do. 4. Review `!mjolnir help` to see what else the bot can do.
## Synapse Module
**This requires Synapse 1.53.0 or higher**
Using the bot to manage your rooms is great, however if you want to use your ban lists
(or someone else's) on your server to affect all of your users then a Synapse module
is needed. Primarily meant to block invites from undesired homeservers/users, Mjolnir's
Synapse module is a way to interpret ban lists and apply them to your entire homeserver.
First, install the module to your Synapse python environment:
```
pip install -e "git+https://github.com/matrix-org/mjolnir.git#egg=mjolnir&subdirectory=synapse_antispam"
```
*Note*: Where your python environment is depends on your installation method. Visit
[#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org) if you're not sure.
Then add the following to your `homeserver.yaml`:
```yaml
modules:
- module: mjolnir.Module
config:
# Prevent servers/users in the ban lists from inviting users on this
# server to rooms. Default true.
block_invites: true
# Flag messages sent by servers/users in the ban lists as spam. Currently
# this means that spammy messages will appear as empty to users. Default
# false.
block_messages: false
# Remove users from the user directory search by filtering matrix IDs and
# display names by the entries in the user ban list. Default false.
block_usernames: false
# The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
# this list cannot be room aliases or permalinks. This server is expected
# to already be joined to the room - Mjolnir will not automatically join
# these rooms.
ban_lists:
- "!roomid:example.org"
#message_max_length:
# Limit the characters in a message (event body) that a client can send in an event on this server.
# By default there is no limit (beyond the the limit the spec enforces on event size).
# Uncomment if you want messages to be limited to 510 characters.
#threshold: 510
# Limit messages only in certain rooms rooms.
# By default all rooms will enforce the limit.
# Uncomment if you want messages to only be subject to character limits in certain rooms.
#rooms:
# - "!vMvyOCeCxHsggkmALd:localhost:9999"
# Also hide messages from remote servers that are over the `message_limit`.
# By default only events from this server will be limited.
# WARNING: Remote users on other servers will still be able to messages over the limit.
# Uncomment to enforce the `message_limit` on events from remote servers.
#remote_servers: true
```
*Note*: Although this is described as a "spam checker", it does much more than fight
spam.
Be sure to change the configuration to match your setup. Your server is expected to
already be participating in the ban lists - if it is not, you will need to have a user
on your homeserver join. The antispam module will not join the rooms for you.
If you change the configuration, you will need to restart Synapse. You'll also need
to restart Synapse to install the plugin.
## Enabling readable abuse reports ## Enabling readable abuse reports
Since version 1.2, Mjölnir offers the ability to replace the Matrix endpoint used Since version 1.2, Mjölnir offers the ability to replace the Matrix endpoint used
@ -198,7 +87,7 @@ Once rust is installed you can install mx-tester like so.
$ cargo install mx-tester $ cargo install mx-tester
``` ```
Once you have mx-tester installed you we will want to build a synapse image with synapse_antispam from the mjolnir project root. Once you have mx-tester installed you we will want to build a synapse image with synapse_antispam from the Mjolnir project root.
``` ```
$ mx-tester build $ mx-tester build

174
config/default.yaml
View File

@ -1,151 +1,177 @@
# Where the homeserver is located (client-server URL). This should point at # Endpoint URL that Mjolnir uses to interact with the matrix homeserver (client-server API),
# pantalaimon if you're using that. # set this to the pantalaimon URL if you're using that.
homeserverUrl: "https://matrix.org" homeserverUrl: "https://matrix.org"
# Endpoint URL that Mjolnir could use to fetch events related to reports (client-server API and /_synapse/),
# Where the homeserver is located (client-server URL). NOT panalaimon. # only set this to the public-internet homeserver client API URL, do NOT set this to the pantalaimon URL.
rawHomeserverUrl: "https://matrix.org" rawHomeserverUrl: "https://matrix.org"
# Matrix Access Token to use, Mjolnir will only use this if pantalaimon.use is false.
# The access token for the bot to use. Do not populate if using Pantalaimon.
accessToken: "YOUR_TOKEN_HERE" accessToken: "YOUR_TOKEN_HERE"
# Pantalaimon options (https://github.com/matrix-org/pantalaimon) # Options related to Pantalaimon (https://github.com/matrix-org/pantalaimon)
pantalaimon: pantalaimon:
# If true, accessToken above is ignored and the username/password below will be # Whether or not Mjolnir will use pantalaimon to access the matrix homeserver,
# used instead. The access token of the bot will be stored in the dataPath. # set to `true` if you're using pantalaimon.
#
# Be sure to point homeserverUrl to the pantalaimon instance.
#
# Mjolnir will log in using the given username and password once,
# then store the resulting access token in a file under dataPath.
use: false use: false
# The username to login with. # The username to login with.
username: mjolnir username: mjolnir
# The password to login with. Can be removed after the bot has logged in once and # The password Mjolnir will login with.
# stored the access token. #
# After successfully logging in once, this will be ignored, so this value can be blanked after first startup.
password: your_password password: your_password
# The directory the bot should store various bits of information in # The path Mjolnir will store its state/data in, leave default ("/data/storage") when using containers.
dataPath: "/data/storage" dataPath: "/data/storage"
# If true (the default), only users in the `managementRoom` can invite the bot # If true (the default), Mjolnir will only accept invites from users present in managementRoom.
# to new rooms.
autojoinOnlyIfManager: true autojoinOnlyIfManager: true
# If `autojoinOnlyIfManager` is false, only the members in this group can invite # If `autojoinOnlyIfManager` is false, only the members in this group can invite
# the bot to new rooms. # the bot to new rooms.
acceptInvitesFromGroup: '+example:example.org' acceptInvitesFromGroup: "+example:example.org"
# If the bot is invited to a room and it won't accept the invite (due to the # Whether Mjolnir should report ignored invites to the management room (if autojoinOnlyIfManager is true).
# conditions above), report it to the management room. Defaults to disabled (no
# reporting).
recordIgnoredInvites: false recordIgnoredInvites: false
# The room ID where people can use the bot. The bot has no access controls, so # The room ID (or room alias) of the management room, anyone in this room can issue commands to Mjolnir.
# anyone in this room can use the bot - secure your room! #
# Mjolnir has no more granular access controls other than this, be sure you trust everyone in this room - secure it!
#
# This should be a room alias or room ID - not a matrix.to URL. # This should be a room alias or room ID - not a matrix.to URL.
# Note: Mjolnir is fairly verbose - expect a lot of messages from it. #
# Note: By default, Mjolnir is fairly verbose - expect a lot of messages in this room.
# (see verboseLogging to adjust this a bit.)
managementRoom: "#moderators:example.org" managementRoom: "#moderators:example.org"
# Set to false to make the management room a bit quieter. # Whether Mjolnir should log a lot more messages in the room,
# mainly involves "all-OK" messages, and debugging messages for when mjolnir checks bans in a room.
verboseLogging: true verboseLogging: true
# The log level for the logs themselves. One of DEBUG, INFO, WARN, and ERROR. # The log level of terminal (or container) output,
# can be one of DEBUG, INFO, WARN and ERROR, in increasing order of importance and severity.
#
# This should be at INFO or DEBUG in order to get support for Mjolnir problems. # This should be at INFO or DEBUG in order to get support for Mjolnir problems.
logLevel: "INFO" logLevel: "INFO"
# Set to false to disable synchronizing the ban lists on startup. If true, this # Whether or not Mjolnir should synchronize policy lists immediately after startup.
# is the same as running !mjolnir sync immediately after startup. # Equivalent to running '!mjolnir sync'.
syncOnStartup: true syncOnStartup: true
# Set to false to prevent Mjolnir from checking its permissions on startup. This # Whether or not Mjolnir should check moderation permissions in all protected rooms on startup.
# is recommended to be left as "true" to catch room permission problems (state # Equivalent to running `!mjolnir verify`.
# resets, etc) before Mjolnir is needed.
verifyPermissionsOnStartup: true verifyPermissionsOnStartup: true
# If true, Mjolnir won't actually ban users or apply server ACLs, but will # Whether or not Mjolnir should actually apply bans and policy lists,
# think it has. This is useful to see what it does in a scenario where the # turn on to trial some untrusted configuration or lists.
# bot might not be trusted fully, yet. Default false (do bans/ACLs).
noop: false noop: false
# Set to true to use /joined_members instead of /state to figure out who is # Whether Mjolnir should check member lists quicker (by using a different endpoint),
# in the room. Using /state is preferred because it means that users are # keep in mind that enabling this will miss invited (but not joined) users.
# banned when they are invited instead of just when they join. Set this to true #
# if the bot is in large rooms or dozens of rooms. # Turn on if your bot is in (very) large rooms, or in large amounts of rooms.
fasterMembershipChecks: false fasterMembershipChecks: false
# A case-insensitive list of ban reasons to automatically redact a user's # A case-insensitive list of ban reasons to have the bot also automatically redact the user's messages for.
# messages for. Typically this is useful to avoid having to type two commands #
# to the bot. Use asterisks to represent globs (ie: "spam*testing" would match # If the bot sees you ban a user with a reason that is an (exact case-insensitive) match to this list,
# "spam for testing" as well as "spamtesting"). # it will also remove the user's messages automatically.
#
# Typically this is useful to avoid having to give two commands to the bot.
# Advanced: Use asterisks to have the reason match using "globs"
# (f.e. "spam*testing" would match "spam for testing" as well as "spamtesting").
#
# See here for more info: https://www.digitalocean.com/community/tools/glob
# Note: Keep in mind that glob is NOT regex!
automaticallyRedactForReasons: automaticallyRedactForReasons:
- "spam" - "spam"
- "advertising" - "advertising"
# A list of rooms to protect (matrix.to URLs) # A list of rooms to protect. Mjolnir will add this to the list it knows from its account data.
#
# It won't, however, add it to the account data.
# Manually add the room via '!mjolnir rooms add' to have it stay protected regardless if this config value changes.
#
# Note: These must be matrix.to URLs
protectedRooms: protectedRooms:
- "https://matrix.to/#/#yourroom:example.org" - "https://matrix.to/#/#yourroom:example.org"
# Set this option to true to protect every room the bot is joined to. Note that # Whether or not to add all joined rooms to the "protected rooms" list
# this effectively makes the protectedRooms and associated commands useless because # (excluding the management room and watched policy list rooms, see below).
# the bot by nature must be joined to the room to protect it.
# #
# Note: the management room is *excluded* from this condition. Add it to the # Note that this effectively makes the protectedRooms and associated commands useless
# protected rooms to protect it. # for regular rooms.
# #
# Note: ban list rooms the bot is watching but didn't create will not be protected. # Note: the management room is *excluded* from this condition.
# Manually add these rooms to the protected rooms list if you want them protected. # Explicitly add it as a protected room to protect it.
#
# Note: Ban list rooms the bot is watching but didn't create will not be protected.
# Explicitly add these rooms as a protected room list if you want them protected.
protectAllJoinedRooms: false protectAllJoinedRooms: false
# Server administration commands, these commands will only work if Mjolnir is # Server administration commands, these commands will only work if Mjolnir is
# a global server administrator # a global server administrator, and the bot's server is a Synapse instance.
admin: admin:
# The `make admin` upgrades the powerlevel of a specified user (or the bot itself) # Whether or not Mjolnir can temporarily take control of any eligible account from the local homeserver who's in the room
# of a room to make them admin of the room (powerlevel 100). # (with enough permissions) to "make" a user an admin.
# #
# This only works if the room has at least one admin on the local homeserver # This only works if a local user with enough admin permissions is present in the room.
# (the homeserver specified in `homeserverUrl` in this file).
enableMakeRoomAdminCommand: false enableMakeRoomAdminCommand: false
# Misc options for command handling and commands # Misc options for command handling and commands
commands: commands:
# If true, Mjolnir will respond to commands like !help and !ban instead of # Whether or not the `!mjolnir` prefix is necessary to submit commands.
# requiring a prefix. This is useful if Mjolnir is the only bot running in
# your management room.
# #
# Note that Mjolnir can be pinged by display name instead of having to use # If `true`, will allow commands like `!ban`, `!help`, etc.
#
# Note: Mjolnir can also be pinged by display name instead of having to use
# the !mjolnir prefix. For example, "my_moderator_bot: ban @spammer:example.org" # the !mjolnir prefix. For example, "my_moderator_bot: ban @spammer:example.org"
# will ban a user. # will address only my_moderator_bot.
allowNoPrefix: false allowNoPrefix: false
# In addition to the bot's display name, !mjolnir, and optionally no prefix # Any additional bot prefixes that Mjolnir will listen to. i.e. adding `mod` will allow `!mod help`.
# above, the bot will respond to these names. The items here can be used either
# as display names or prefixed with exclamation points.
additionalPrefixes: additionalPrefixes:
- "mjolnir_bot" - "mjolnir_bot"
# If true, ban commands that use wildcard characters require confirmation with # Whether or not commands with a wildcard (*) will require an additional `--force` argument
# an extra `--force` argument # in the command to be able to be submitted.
confirmWildcardBan: true confirmWildcardBan: true
# Configuration specific to certain toggleable protections # Configuration specific to certain toggle-able protections
protections: protections:
# Configuration for the wordlist plugin, which can ban users based if they say certain # Configuration for the wordlist plugin, which can ban users based if they say certain
# blocked words shortly after joining. # blocked words shortly after joining.
wordlist: wordlist:
# A list of words which should be monitored by the bot. These will match if any part # A list of case-insensitive keywords that the WordList protection will watch for from new users.
# of the word is present in the message in any case. e.g. "hello" also matches #
# "HEllO". Additionally, regular expressions can be used. # WordList will ban users who use these words when first joining a room, so take caution when selecting them.
#
# For advanced usage, regex can also be used, see the following links for more information;
# - https://www.digitalocean.com/community/tutorials/an-introduction-to-regular-expressions
# - https://regexr.com/
# - https://regexone.com/
words: words:
- "CaSe" - "LoReM"
- "InSeNsAtIve" - "IpSuM"
- "WoRd" - "DoLoR"
- "LiSt" - "aMeT"
# How long after a user joins the server should the bot monitor their messages. After # For how long (in minutes) the user is "new" to the WordList plugin.
# this time, users can say words from the wordlist without being banned automatically. #
# Set to zero to disable (users will always be banned if they say a bad word) # After this time, the user will no longer be banned for using a word in the above wordlist.
#
# Set to zero to disable the timeout and make users *always* appear "new".
# (users will always be banned if they say a bad word)
minutesBeforeTrusting: 20 minutesBeforeTrusting: 20
# Options for monitoring the health of the bot # Options for advanced monitoring of the health of the bot.
health: health:
# healthz options. These options are best for use in container environments # healthz options. These options are best for use in container environments
# like Kubernetes to detect how healthy the service is. The bot will report # like Kubernetes to detect how healthy the service is. The bot will report

2
docs/moderators.md
View File

@ -11,6 +11,7 @@ information about the Synapse module can be found in the README.
If you're actively dealing with an incident, here's what you need to know: If you're actively dealing with an incident, here's what you need to know:
* Always talk to Mjolnir in your coordination room. * Always talk to Mjolnir in your coordination room.
* `!mjolnir room add <room>` will add a room to your "protected rooms", roms where mjolnir will propagate bans.
* `!mjolnir ban <shortcode> user @spammer:example.org` will ban someone. * `!mjolnir ban <shortcode> user @spammer:example.org` will ban someone.
* `!mjolnir ban <shortcode> server example.org` will ban a whole server. * `!mjolnir ban <shortcode> server example.org` will ban a whole server.
* `!mjolnir rules` will tell you what the shortcodes are for your ban lists (needed above). * `!mjolnir rules` will tell you what the shortcodes are for your ban lists (needed above).
@ -19,6 +20,7 @@ If you're actively dealing with an incident, here's what you need to know:
* `!mjolnir protections` will show you your available protections - green circles mean enabled. * `!mjolnir protections` will show you your available protections - green circles mean enabled.
* `!mjolnir enable <protection>` to turn on a protection. * `!mjolnir enable <protection>` to turn on a protection.
* `!mjolnir move <room alias> <room alias/ID>` Moves a room alias to a new room ID * `!mjolnir move <room alias> <room alias/ID>` Moves a room alias to a new room ID
* `!mjolnir verify` makes sure the bot has all required permissions to enact moderation (in all the protected rooms).
## How Mjolnir works ## How Mjolnir works

48
docs/setup.md Normal file
View File

@ -0,0 +1,48 @@
# Setting up Mjolnir
It is recommended to use [Pantalaimon](https://github.com/matrix-org/pantalaimon) so your management
room can be encrypted. This also applies if you are looking to moderate an encrypted room.
If you aren't using encrypted rooms anywhere, get an access token by opening Element in a
seperate browser profile or incognito tab, and log in as the bot. Then, go to "All Settings", "Help & About", and
click the little triangle next to "Access token". Copy and paste that into your config under `accessToken`.
**Note**: Do not log out, just close the window, otherwise the access token will be invalidated.
It's recommended to setup mjolnir as "close" to your server as possible (latency-wise), so that it
may react swiftly to commands, and quickly apply protections.
It's also recommended to turn off ratelimiting for a mjolnir bot, see [matrix-org/synapse#6286](https://github.com/matrix-org/synapse/issues/6286) and
[the synapse admin API documentation](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#set-ratelimit) for more information.
**Note**: To deactivate users, move aliases, shutdown rooms, Mjolnir will need to be a server
admin, and the server needs to be Synapse.
See the [sample configuration](../config/default.yaml) for documentation about individual config keys.
## Installation
On a high level, installing Mjolnir works like the following;
1. Creating an account for mjolnir.
(Optional) Disable rate limits for that account.
2. Install mjolnir, see below.
3. Configure mjolnir see [further below](#post-install).
4. Start mjolnir.
Mjolnir can be installed in two ways, via Docker, or building it yourself.
See the below links for corresponding installation documentation;
- [Docker](./setup_docker.md)
- [Building It](./setup_selfbuild.md)
## Post-install
After installation, create a room, and ensure the mjolnir has joined. This will be your "management room".
If you're using pantalaimon, this room can be encrypted. If you're not using pantalaimon, this room **can not** be encrypted.
Acquire the room ID of this room, in Element Web you can find this via `(Room Name) -> Settings -> Advanced -> "Internal Room ID"`.
In your configuration, set `managementRoom` to this Room ID, now Mjolnir will only respond to commands originating from that room. If you want to upgrade your room in the future, you will have to update the configuration with it, or set it to an alias that corresponds to that room ID.
You can now start mjolnir. If everything went well, it should now send a bunch of messages in that room, signalling how it is booting up, and its current status.

78
docs/setup_docker.md Normal file
View File

@ -0,0 +1,78 @@
Mjolnir is available on the Docker Hub as [`matrixdotorg/mjolnir`](https://hub.docker.com/r/matrixdotorg/mjolnir).
Using docker, mjolnir can be setup and ran in either of two ways;
- Docker Run
- Docker Compose
Docker run will fire off a single-use container that is tied to your terminal's lifetime. (if you close the terminal, you shut down the bot)
Docker Compose can manage containers in the background, read a "compose" file, and automatically
recreate/restart relevant containers (upon `docker-compose up -d`) if they diverge from the file. It
can also easily read logs and manage the lifecycle of these containers. (start/stop/restart)
# Prerequisites
Before any other steps, a configuration file must be prepared.
Please go through [the sample configuration file's documentation](../config/default.yaml), download it, and rename it `production.yaml`.
You should go through and edit values to your liking, afterwards, pick a directory that'll be the root of all your mjolnir data files (i.e. `./mjolnir` from the home directory on your server), create a new directory called `config`, place the file there.
In short, please make sure that the mjolnir configuration exists under `./config/production.yaml` relative to the directory you've chosen, else mjolnir will not recognise it.
# Docker Run
Run the following command in your terminal, replace `./mjolnir` with the root directory of your config, if it is in another spot.
```bash
docker run --rm -it -v ./mjolnir:/data matrixdotorg/mjolnir:latest
```
# Docker Compose
Take the following file, and copy-paste it in `docker-compose.yml`;
```yaml
version: "3.3"
services:
mjolnir:
image: matrixdotorg/mjolnir:latest
restart: unless-stopped
volumes:
- ./mjolnir:/data
```
If you have pantalaimon installed, you can include it in this compose file as follows;
```yaml
version: "3.3"
services:
pantalaimon:
build: ./pantalaimon
container_name: pantalaimon
restart: unless-stopped
volumes:
- ./pantalaimon_data:/data
ports:
- 8008:8008
mjolnir:
image: matrixdotorg/mjolnir:latest
restart: unless-stopped
volumes:
- ./mjolnir:/data
```
**Note**: At the moment, pantalaimon does not have a Docker Hub image, so `./pantalaimon` needs to be the checked-out github repository, which you can do with `git clone https://github.com/matrix-org/pantalaimon`.
**Note**: In this configuration, you can access pantalaimon by using `pantalaimon` as a hostname, e.g. `http://pantalaimon:8080/` as `homeserverUrl`.
Replace `./mjolnir` (and optionally `./pantalaimon_data`) with the correct directories.
Then call `docker-compose up -d` while in the same directory as `docker-compose.yml` to pull, create, and start the containers.
- Use `docker-compose stop` to stop all containers, or `docker-compose stop mjolnir` to stop only the `mjolnir` container.
- Use `docker-compose restart mjolnir` to restart the mjolnir container, omit to restart all containers.
- Use `docker-compose down` to stop and remove all containers.
- Use `docker-compose logs` to display container logs, append `-f` to follow the logs in your terminal, append `--tail 100` to only show the latest 100 entries.

15
docs/setup_selfbuild.md Normal file
View File

@ -0,0 +1,15 @@
To build mjolnir, you have to have installed `yarn` 1.x and Node 14.
```bash
git clone https://github.com/matrix-org/mjolnir.git
cd mjolnir
yarn install
yarn build
# Copy and edit the config. It *is* recommended to change the data path.
cp config/default.yaml config/development.yaml
nano config/development.yaml
node lib/index.js
```

64
docs/synapse_module.md Normal file
View File

@ -0,0 +1,64 @@
**This requires Synapse 1.53.0 or higher**
Using the bot to manage your rooms is great, however if you want to use your ban lists
(or someone else's) on your server to affect all of your users then a Synapse module
is needed. Primarily meant to block invites from undesired homeservers/users, Mjolnir's
Synapse module is a way to interpret ban lists and apply them to your entire homeserver.
First, install the module to your Synapse python environment:
```
pip install -e "git+https://github.com/matrix-org/mjolnir.git#egg=mjolnir&subdirectory=synapse_antispam"
```
*Note*: Where your python environment is depends on your installation method. Visit
[#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org) if you're not sure.
Then add the following to your `homeserver.yaml`:
```yaml
modules:
- module: mjolnir.Module
config:
# Prevent servers/users in the ban lists from inviting users on this
# server to rooms. Default true.
block_invites: true
# Flag messages sent by servers/users in the ban lists as spam. Currently
# this means that spammy messages will appear as empty to users. Default
# false.
block_messages: false
# Remove users from the user directory search by filtering matrix IDs and
# display names by the entries in the user ban list. Default false.
block_usernames: false
# The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
# this list cannot be room aliases or permalinks. This server is expected
# to already be joined to the room - Mjolnir will not automatically join
# these rooms.
ban_lists:
- "!roomid:example.org"
#message_max_length:
# Limit the characters in a message (event body) that a client can send in an event on this server.
# By default there is no limit (beyond the the limit the spec enforces on event size).
# Uncomment if you want messages to be limited to 510 characters.
#threshold: 510
# Limit messages only in certain rooms rooms.
# By default all rooms will enforce the limit.
# Uncomment if you want messages to only be subject to character limits in certain rooms.
#rooms:
# - "!vMvyOCeCxHsggkmALd:localhost:9999"
# Also hide messages from remote servers that are over the `message_limit`.
# By default only events from this server will be limited.
# WARNING: Remote users on other servers will still be able to messages over the limit.
# Uncomment to enforce the `message_limit` on events from remote servers.
#remote_servers: true
```
*Note*: Although this is described as a "spam checker", it does much more than fight
spam.
Be sure to change the configuration to match your setup. Your server is expected to
already be participating in the ban lists - if it is not, you will need to have a user
on your homeserver join. The antispam module will not join the rooms for you.
If you change the configuration, you will need to restart Synapse. You'll also need
to restart Synapse to install the plugin.