| 1 | # Settings |
| 2 | |
| 3 | On this page you will find information about global matterbridge settings. Most of these settings can be applied to specific gateways, and those marked **GENERAL** can be placed in the `[general]` configuration dictionary for setting it across all gateways. |
| 4 | |
| 5 | > [!TIP] |
| 6 | > Settings specific to a certain protocol can be found in the corresponding folder in the |
| 7 | > [protocols/](protocols/) documentation folder. API settings for can be found in the |
| 8 | > [api/](api/) documentation folder. |
| 9 | |
| 10 | # Info |
| 11 | |
| 12 | * **OPTIONAL:** this setting isn't enabled by default. |
| 13 | * **RELOADABLE:** this setting can be reloaded by editing the configuration. No restart of matterbridge is required. |
| 14 | * **ALL:** this setting is usable with all bridges. |
| 15 | * **GENERAL:** this setting can be also set under `[general]` which means it's active for all bridges. |
| 16 | |
| 17 | # Shared |
| 18 | Only settings which have the `ALL` setting are usable for all bridges. |
| 19 | |
| 20 | ## EditDisable |
| 21 | Disable sending of edits to other bridges |
| 22 | |
| 23 | Setting: OPTIONAL, RELOADABLE \ |
| 24 | Format: boolean \ |
| 25 | Example: enable it |
| 26 | |
| 27 | `EditDisable=true` |
| 28 | |
| 29 | ## EditSuffix |
| 30 | Message to be appended to every edited message |
| 31 | |
| 32 | Setting: OPTIONAL, RELOADABLE \ |
| 33 | Format: string \ |
| 34 | Example: |
| 35 | |
| 36 | `EditSuffix=" (edited)"` |
| 37 | |
| 38 | ## IgnoreMessages |
| 39 | Messages you want to ignore.\ |
| 40 | Messages matching these regexp will be ignored and not sent to other bridges.\ |
| 41 | See https://regex-golang.appspot.com/assets/html/index.html for more regex info. |
| 42 | |
| 43 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 44 | Format: space seperated regex string \ |
| 45 | Example: ignores messages starting with ~~ or messages containing badword |
| 46 | |
| 47 | `IgnoreMessages="^~~ badword"` |
| 48 | |
| 49 | ## IgnoreNicks |
| 50 | Nicks you want to ignore.\ |
| 51 | Messages from those users will not be sent to other bridges. |
| 52 | |
| 53 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 54 | Format: space seperated regex string \ |
| 55 | Example: ignore messages from ircspammer1 and ircspammer2 |
| 56 | |
| 57 | `IgnoreNicks="ircspammer1 ircspammer2"` |
| 58 | |
| 59 | ## Label |
| 60 | Extra label that can be used in the `RemoteNickFormat` |
| 61 | |
| 62 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 63 | Format: string \ |
| 64 | Example: add the label `mychat` |
| 65 | |
| 66 | `Label="mychat"` |
| 67 | |
| 68 | ## PrefixMessagesWithNick |
| 69 | Whether to prefix messages from other bridges to with the sender's nick. |
| 70 | Useful if username overrides for incoming webhooks isn't enabled. |
| 71 | If you set PrefixMessagesWithNick to true, each message |
| 72 | from other bridges will by default be prefixed by "bridge-" + nick. You can, |
| 73 | however, modify how the messages appear, by setting (and modifying) `RemoteNickFormat` |
| 74 | |
| 75 | Setting: OPTIONAL, RELOADABLE \ |
| 76 | Format: boolean \ |
| 77 | Example: |
| 78 | |
| 79 | `PrefixMessagesWithNick=true` |
| 80 | |
| 81 | |
| 82 | ## RemoteNickFormat |
| 83 | Defines how remote users appear on this bridge. \ |
| 84 | The string "{NICK}" (case sensitive) will be replaced by the actual nick / username. \ |
| 85 | The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge. \ |
| 86 | The string "{LABEL}" (case sensitive) will be replaced by label= field of the sending bridge. \ |
| 87 | The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge. \ |
| 88 | The string "{GATEWAY}" (case sensitive) will be replaced by the origin gateway name that is replicating the message. \ |
| 89 | The string "{CHANNEL}" (case sensitive) will be replaced by the origin channel name used by the bridge. \ |
| 90 | The string "{TENGO}" (case sensitive) will be replaced by the output of the RemoteNickFormat script under `[tengo]` \ |
| 91 | The string "{NOPINGNICK}" (case sensitive) will be replaced by the actual nick / username, but with a ZWSP inside the nick, so the irc user with the same nick won't get pinged. See https://github.com/42wim/matterbridge/issues/175 for more information |
| 92 | |
| 93 | Setting: OPTIONAL, RELOADABLE, GENERAL, ALL \ |
| 94 | Format: string \ |
| 95 | Example: add PROTOCOL and NICK |
| 96 | |
| 97 | `RemoteNickFormat="[{PROTOCOL}] <{NICK}> "` |
| 98 | |
| 99 | ## ReplaceMessages |
| 100 | Messages you want to replace. \ |
| 101 | It replaces outgoing messages from the bridge. \ |
| 102 | So you need to place it by the sending bridge definition.\ |
| 103 | Regular expressions supported. |
| 104 | |
| 105 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 106 | Format: [ ["from1","to1"],["from2","to2"] ] \ |
| 107 | Example: this replaces cat => dog and sleep => awake |
| 108 | |
| 109 | `ReplaceMessages=[ ["cat","dog"], ["sleep","awake"] ]` |
| 110 | |
| 111 | ## ReplaceNicks |
| 112 | Nicks you want to replace. \ |
| 113 | See `ReplaceMessages` for syntax |
| 114 | |
| 115 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 116 | Format: [ ["from1","to1"],["from2","to2"] ] \ |
| 117 | Example: this replaces user-- => user |
| 118 | |
| 119 | `ReplaceNicks=[ ["user--","user"] ]` |
| 120 | |
| 121 | ## ShowJoinPart |
| 122 | Enable to show users joins/parts from other bridges \ |
| 123 | Currently works for messages from the following bridges: irc, mattermost, slack |
| 124 | |
| 125 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 126 | Format: boolean \ |
| 127 | Example: enable it |
| 128 | |
| 129 | `ShowJoinPart=true` |
| 130 | |
| 131 | ## ShowTopicChange |
| 132 | Enable to show topic changes from other bridges. \ |
| 133 | Only works hiding/show topic changes from slack bridge for now. |
| 134 | |
| 135 | Setting: OPTIONAL, RELOADABLE, ALL \ |
| 136 | Format: boolean \ |
| 137 | Example: enable it |
| 138 | |
| 139 | `ShowTopicChange=true` |
| 140 | |
| 141 | ## SkipTLSVerify |
| 142 | Enable to not verify the certificate on your server. |
| 143 | e.g. when using selfsigned certificates |
| 144 | |
| 145 | Setting: OPTIONAL \ |
| 146 | Format: boolean \ |
| 147 | Example: enable it |
| 148 | |
| 149 | `SkipTLSVerify=true` |
| 150 | |
| 151 | ## StripNick |
| 152 | StripNick only allows alphanumerical nicks. See https://github.com/42wim/matterbridge/issues/285 |
| 153 | It will strip other characters from the nick |
| 154 | |
| 155 | Setting: OPTIONAL, RELOADABLE, GENERAL, ALL \ |
| 156 | Format: boolean \ |
| 157 | Example: enable it |
| 158 | |
| 159 | `StripNick=true` |
| 160 | |
| 161 | ## UseLocalAvatar |
| 162 | |
| 163 | UseLocalAvatar specifies source bridges for which an avatar should be 'guessed' when an incoming message has no avatar. This works by comparing the username of the message to an existing Discord user, and using the avatar of the Discord user. (Substitute "Discord" with another platform, if used on another platform.) |
| 164 | |
| 165 | On Discord, this only works if `WebhookURL` is set (AND the message has no avatar). |
| 166 | |
| 167 | At the moment, this setting is only available for Discord. |
| 168 | |
| 169 | Setting: OPTIONAL, RELOADABLE |
| 170 | Format: `["gateway.account1", "gateway.account2", "gateway"]` |
| 171 | Example: `["irc"]` - this example will guess the avatar coming from the `irc` platform |
| 172 | |
| 173 | # General |
| 174 | |
| 175 | Configuration that can be set under `[general]` |
| 176 | |
| 177 | ## IgnoreFailureOnStart |
| 178 | Allows you to ignore failing bridges on startup. |
| 179 | Matterbridge will disable the failed bridge and continue with the other ones. \ |
| 180 | Context: https://github.com/42wim/matterbridge/issues/455 |
| 181 | |
| 182 | Setting: OPTIONAL, RELOADABLE, GENERAL \ |
| 183 | Format: boolean \ |
| 184 | Example: enable it |
| 185 | |
| 186 | `IgnoreFailureOnStart=true` |
| 187 | |
| 188 | ## LogFile |
| 189 | |
| 190 | LogFile defines the location of a file to write logs into, rather than stdout. |
| 191 | Logging will still happen on stdout if the file cannot be open for #writing, or if the value is empty. |
| 192 | Note that the log won't roll, so you might want to use logrotate(8) with this feature. |
| 193 | |
| 194 | Setting: OPTIONAL, GENERAL \ |
| 195 | Format: string \ |
| 196 | Example: |
| 197 | |
| 198 | `LogFile="/var/log/matterbridge.log"` |
| 199 | |
| 200 | ## MediaDownloadBlacklist |
| 201 | Allows you to blacklist specific files from being downloaded. |
| 202 | Filenames matching these regexp will not be download/uploaded to the mediaserver. \ |
| 203 | You can use regex for this, see https://regex-golang.appspot.com/assets/html/index.html for more regex info |
| 204 | |
| 205 | Setting: OPTIONAL, RELOADABLE, GENERAL \ |
| 206 | Format: string array \ |
| 207 | Example: do not upload html and htm extension |
| 208 | |
| 209 | `MediaDownloadBlacklist=[".html$",".htm$"]` |
| 210 | |
| 211 | ## MediaDownloadPath |
| 212 | MediaDownloadPath is the filesystem path where the media file will be placed, instead of uploaded, for if Matterbridge has write access to the directory your webserver is serving. [More information](https://github.com/matterbridge-org/matterbridge/blob/master/docs/advanced/mediaserver.md) |
| 213 | |
| 214 | Setting: OPTIONAL, RELOADABLE, GENERAL \ |
| 215 | Format: string \ |
| 216 | Example: |
| 217 | |
| 218 | `MediaDownloadPath="/srv/http/yourserver.com/public/download"` |
| 219 | |
| 220 | ## MediaDownloadSize |
| 221 | Maximum size in bytes matterbridge will download for use with upload to the |
| 222 | media server or to other bridges. |
| 223 | |
| 224 | Setting: OPTIONAL, RELOADABLE, GENERAL \ |
| 225 | Format: int \ |
| 226 | Default: 10000000 (1 megabyte) \ |
| 227 | Example: |
| 228 | |
| 229 | `MediaDownloadSize=1000000` |
| 230 | |
| 231 | |
| 232 | ## MediaServerDownload |
| 233 | The MediaServerDownload will be used so that bridges without native uploading support: |
| 234 | irc and xmpp will be shown links to the files on MediaServerDownload |
| 235 | More information https://github.com/42wim/matterbridge/wiki/Mediaserver-setup-%28advanced%29 |
| 236 | |
| 237 | Setting: OPTIONAL, RELOADABLE, GENERAL \ |
| 238 | Format: string \ |
| 239 | Example: |
| 240 | |
| 241 | `MediaServerDownload="https://youserver.com/download"` |
| 242 | |
