| 1 | # XMPP settings |
| 2 | |
| 3 | > [!TIP] |
| 4 | > This page contains the details about xmpp settings. More general information about xmpp support in matterbridge can be found in [README.md](README.md). |
| 5 | |
| 6 | > [!NOTE] |
| 7 | > XMPP (the protocol) is also known as Jabber (the open federation). These |
| 8 | > two terms are used interchangeably. To learn more about Jabber/XMPP, |
| 9 | > see [joinjabber.org](https://joinjabber.org/). |
| 10 | |
| 11 | ## Jid |
| 12 | |
| 13 | Jabber Identifier, the XMPP login for matterbridge's account. |
| 14 | |
| 15 | - Setting: **REQUIRED** |
| 16 | - Format: *string* |
| 17 | - Example: |
| 18 | ```toml |
| 19 | Jid="user@example.com" |
| 20 | ``` |
| 21 | |
| 22 | ## MUC |
| 23 | |
| 24 | The Multi User Chat (MUC) server where the bot will find the defined gateway |
| 25 | channels. At the moment, bridging a room on a different MUC requires creating |
| 26 | a separate account entry in the configuration. |
| 27 | |
| 28 | TODO: test if a matterbridge instance can be connected to the same account |
| 29 | with two configurations at the same time; this is allowed by XMPP |
| 30 | protocol but requires matterbridge to behave properly in terms |
| 31 | of XMPP protocol |
| 32 | |
| 33 | - Setting: **REQUIRED** |
| 34 | - Format: *string* |
| 35 | - Example: |
| 36 | ```toml |
| 37 | Muc="conference.jabber.example.com" |
| 38 | ``` |
| 39 | |
| 40 | ## Nick |
| 41 | |
| 42 | Your nick in the rooms |
| 43 | |
| 44 | - Setting: **REQUIRED** |
| 45 | - Format: *string* |
| 46 | - Example: |
| 47 | ```toml |
| 48 | Nick="xmppbot" |
| 49 | ``` |
| 50 | |
| 51 | ## NoTLS (DEPRECATED) |
| 52 | |
| 53 | > [!WARNING] |
| 54 | > This setting has been deprecated. matterbridge will refuse to start if you are using it. |
| 55 | > You should use the new `UseDirectTls` and `NoStartTls` settings instead. |
| 56 | |
| 57 | - Setting: **OPTIONAL** |
| 58 | - Format: *boolean* |
| 59 | - Example: |
| 60 | ```toml |
| 61 | NoTLS=true |
| 62 | ``` |
| 63 | |
| 64 | ## UseDirectTLS |
| 65 | |
| 66 | Enables direct TLS connection to your server. Most servers by default only support StartTLS, |
| 67 | so this option should only be enabled if you know what you are doing. When `UseDirectTLS` is |
| 68 | not set, and `NoStartTls` is enabled, a plaintext connection is established, which |
| 69 | should only be used in a local testing environment. |
| 70 | |
| 71 | - Setting: **OPTIONAL** |
| 72 | - Format: *boolean* |
| 73 | - Example: |
| 74 | ```toml |
| 75 | UseDirectTLS=true |
| 76 | ``` |
| 77 | |
| 78 | ## NoStartTLS |
| 79 | |
| 80 | Disable StartTLS connection to your server. If you'd like to use direct TLS, enable |
| 81 | the `UseDirectTLS` setting. Otherwise, a plaintext connection is established, which |
| 82 | should only be used in a local testing environment. |
| 83 | |
| 84 | - Setting: **OPTIONAL** |
| 85 | - Format: *boolean* |
| 86 | - Example: |
| 87 | ```toml |
| 88 | NoStartTLS=true |
| 89 | ``` |
| 90 | |
| 91 | ## Password |
| 92 | |
| 93 | Password for the Jid's account. |
| 94 | |
| 95 | - Setting: **REQUIRED** |
| 96 | - Format: *string* |
| 97 | - Example: |
| 98 | ```toml |
| 99 | Password="yourpass" |
| 100 | ``` |
| 101 | |
| 102 | ## Server |
| 103 | |
| 104 | XMPP server to connect to. |
| 105 | |
| 106 | - Setting: **REQUIRED** |
| 107 | - Format: *string* (hostname:port) |
| 108 | - Example: |
| 109 | ```toml |
| 110 | Server="jabber.example.com:5222" |
| 111 | ``` |
| 112 | |
| 113 | ## Mechanism |
| 114 | |
| 115 | Force an explicit SASL mechanism for authentication. This is a very advanced setting |
| 116 | when debugging authentication problems and potential upstream go-xmpp authentication |
| 117 | bugs. If you don't understand it, you don't need it. |
| 118 | |
| 119 | - Setting: **OPTIONAL** |
| 120 | - Format: *string* |
| 121 | - Example: |
| 122 | ```toml |
| 123 | Mechanism="PLAIN" |
| 124 | ``` |
| 125 | |
| 126 | ## NoPLAIN |
| 127 | |
| 128 | Prevent using `PLAIN` SASL authentication to the server. This is an advanced setting |
| 129 | which is incompatible with many servers (eg. those using LDAP auth). When enabled, |
| 130 | this setting will make sure your configured password is *never* sent to the server, |
| 131 | only establishing a secure handshake such as [SCRAM](https://en.wikipedia.org/wiki/Salted_Challenge_Response_Authentication_Mechanism). |
| 132 | |
| 133 | - Setting: **OPTIONAL** |
| 134 | - Format: *boolean* |
| 135 | - Example: |
| 136 | ```toml |
| 137 | NoPLAIN=true |
| 138 | ``` |
| 139 | |
