diff --git a/docs/configuring-playbook-bridge-appservice-kakaotalk.md b/docs/configuring-playbook-bridge-appservice-kakaotalk.md index e10f880a8..448a84e58 100644 --- a/docs/configuring-playbook-bridge-appservice-kakaotalk.md +++ b/docs/configuring-playbook-bridge-appservice-kakaotalk.md @@ -8,9 +8,13 @@ See the project's [documentation](https://src.miscworks.net/fair/matrix-appservi ## Prerequisite (optional) +### Enable Shared Secret Auth + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -20,9 +24,7 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_appservice_kakaotalk_enabled: true ``` -You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. - -### Additional configuration +### Extending the configuration There are some additional things you may wish to configure about the bridge. @@ -52,26 +54,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password. - -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature +You then need to send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password. diff --git a/docs/configuring-playbook-bridge-appservice-webhooks.md b/docs/configuring-playbook-bridge-appservice-webhooks.md index 1746fb80f..e4d212f46 100644 --- a/docs/configuring-playbook-bridge-appservice-webhooks.md +++ b/docs/configuring-playbook-bridge-appservice-webhooks.md @@ -48,7 +48,7 @@ To use the bridge, you need to invite the bridge bot user to your room in either - Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room) - Add the bridge bot to a private channel (personal channels imply you being an administrator) -You then need to send a message to the bridge bot in order to receive a private message including the webhook link: +You then need to send a message to the bridge bot to receive a private message including the webhook link: ``` !webhook diff --git a/docs/configuring-playbook-bridge-beeper-linkedin.md b/docs/configuring-playbook-bridge-beeper-linkedin.md index 8fea2ec93..979c188c1 100644 --- a/docs/configuring-playbook-bridge-beeper-linkedin.md +++ b/docs/configuring-playbook-bridge-beeper-linkedin.md @@ -1,9 +1,19 @@ # Setting up Beeper Linkedin bridging (optional) -The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges +The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the mautrix bridges. See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you. +## Prerequisite + +### Enable Appservice Double Puppet or Shared Secret Auth (optional) + +If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. + ## Adjusting the playbook configuration To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -12,25 +22,13 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_beeper_linkedin_enabled: true ``` -There are some additional things you may wish to configure about the bridge before you continue. +### Extending the configuration -Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: +There are some additional things you may wish to configure about the bridge. -```yaml -matrix_beeper_linkedin_bridge_encryption_allow: true -matrix_beeper_linkedin_bridge_encryption_default: true -``` +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. -If you would like to be able to administrate the bridge from your account it can be configured like this: - -```yaml -matrix_beeper_linkedin_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure. +**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_beeper_linkedin_`. ## Installing @@ -49,23 +47,11 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. -## Set up Double Puppeting by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - ## Usage To use the bridge, you need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account. - -If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. - -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so. +You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account. ## Troubleshooting diff --git a/docs/configuring-playbook-bridge-mautrix-bridges.md b/docs/configuring-playbook-bridge-mautrix-bridges.md index 24576ab94..6fa4e0a68 100644 --- a/docs/configuring-playbook-bridge-mautrix-bridges.md +++ b/docs/configuring-playbook-bridge-mautrix-bridges.md @@ -27,6 +27,8 @@ Different levels of permission can be granted to users. For example, to **config matrix_admin: "@alice:{{ matrix_domain }}" ``` +If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default. + **Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with: ```yaml @@ -84,6 +86,8 @@ You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` ```yaml matrix_mautrix_SERVICENAME_configuration_extension_yaml: | bridge: + relay: + enabled: true permissions: '@alice:{{ matrix_domain }}': admin encryption: @@ -153,7 +157,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login` to the bridge bot to get started. You can learn more here about authentication from the bridge's official documentation on Authentication: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html +For details about the next steps, refer to each bridge's individual documentation page. If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md index df93b246c..9db84cd82 100644 --- a/docs/configuring-playbook-bridge-mautrix-discord.md +++ b/docs/configuring-playbook-bridge-mautrix-discord.md @@ -1,5 +1,7 @@ # Setting up Mautrix Discord bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + **Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook. - For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing. - For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook. @@ -18,7 +20,9 @@ If this is a dealbreaker for you, consider using one of the other Discord bridge If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -28,16 +32,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_discord_enabled: true ``` -You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. - -### Additional configuration +### Extending the configuration There are some additional things you may wish to configure about the bridge. -Take a look at: - -- `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file -- `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -60,6 +60,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ### Logging in +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/discord/authentication.html). + #### Method 1: Login using QR code (recommended) For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone. @@ -83,26 +85,6 @@ To acquire the token, open Discord in a private browser window. Then open the de - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire` 8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function. -### 💡 Set up Double Puppeting +### Relaying -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature +The bridge supports using Discord's webhook feature to relay messages from Matrix users who haven't logged into the bridge. See [the official documentation](https://docs.mau.fi/bridges/go/discord/relay.html#setup) for setting up webhook relaying. diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index a0d55b62b..09124f8b7 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -1,16 +1,22 @@ # Setting up Mautrix Facebook bridging (optional, deprecated) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + **Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md). Consider using that bridge instead of this one. The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you. -See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you. +See the project's [documentation](https://github.com/mautrix/facebook/blob/master/README.md) to learn what it does and why it might be useful to you. ## Prerequisite (optional) +### Enable Shared Secret Auth + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -20,40 +26,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_facebook_enabled: true ``` -There are some additional things you may wish to configure about the bridge before you continue. +### Extending the configuration -Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: +There are some additional things you may wish to configure about the bridge. -```yaml -matrix_mautrix_facebook_configuration_extension_yaml: | - bridge: - encryption: - allow: true - default: true -``` - -If you would like to be able to administrate the bridge from your account it can be configured like this: - -```yaml -matrix_mautrix_facebook_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -Using both would look like - -```yaml -matrix_mautrix_facebook_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin - encryption: - allow: true - default: true -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -76,32 +53,10 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. +You then need to send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature - ## Troubleshooting ### Facebook rejecting login attempts and forcing you to change password diff --git a/docs/configuring-playbook-bridge-mautrix-gmessages.md b/docs/configuring-playbook-bridge-mautrix-gmessages.md index 40305e06b..5339e67ef 100644 --- a/docs/configuring-playbook-bridge-mautrix-gmessages.md +++ b/docs/configuring-playbook-bridge-mautrix-gmessages.md @@ -1,14 +1,18 @@ # Setting up Mautrix Google Messages bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-gmessages](https://github.com/mautrix/gmessages) for you, for bridging to [Google Messages](https://messages.google.com/). See the project's [documentation](https://docs.mau.fi/bridges/go/gmessages/index.html) to learn what it does and why it might be useful to you. ## Prerequisite (optional) +### Enable Appservice Double Puppet + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -18,6 +22,13 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_gmessages_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -39,24 +50,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-gmessages` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-googlechat.md b/docs/configuring-playbook-bridge-mautrix-googlechat.md index 2b077dfcf..4b179c139 100644 --- a/docs/configuring-playbook-bridge-mautrix-googlechat.md +++ b/docs/configuring-playbook-bridge-mautrix-googlechat.md @@ -1,14 +1,20 @@ # Setting up Mautrix Google Chat bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-googlechat](https://github.com/mautrix/googlechat) for you. See the project's [documentation](https://docs.mau.fi/bridges/python/googlechat/index.html) to learn what it does and why it might be useful to you. ## Prerequisite (optional) +### Enable Appservice Double Puppet or Shared Secret Auth + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -18,6 +24,13 @@ To enable the [Google Chat](https://chat.google.com/) bridge, add the following matrix_mautrix_googlechat_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -39,34 +52,10 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions. +You then need to send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions. Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools. Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages. You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html). - -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature diff --git a/docs/configuring-playbook-bridge-mautrix-hangouts.md b/docs/configuring-playbook-bridge-mautrix-hangouts.md index e2a808ec3..8936217cd 100644 --- a/docs/configuring-playbook-bridge-mautrix-hangouts.md +++ b/docs/configuring-playbook-bridge-mautrix-hangouts.md @@ -1,16 +1,20 @@ # Setting up Mautrix Hangouts bridging (optional, deprecated) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + 💡 **Note**: This bridge has been deprecated in favor of [Google Chat bridge](https://github.com/mautrix/googlechat), which can be installed using [this playbook](configuring-playbook-bridge-mautrix-googlechat.md). Installing the mautrix-hangouts bridge is **no longer possible**. For now, this documentation page remains here for historical purposes. The playbook can install and configure [mautrix-hangouts](https://github.com/mautrix/hangouts) for you. -See the project's [documentation](https://docs.mau.fi/bridges/python/hangouts/index.html) to learn what it does and why it might be useful to you. - ## Prerequisite (optional) +### Enable Shared Secret Auth + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -20,6 +24,12 @@ To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the fo matrix_mautrix_hangouts_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -41,32 +51,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions. +You then need to send `login` to the bridge bot to receive a link to the portal from which you can enable the bridging. Open the link sent by the bot and follow the instructions. Automatic login may not work. If it does not, reload the page and select the "Manual login" checkbox before starting. Manual login involves logging into your Google account normally and then manually getting the OAuth token from browser cookies with developer tools. Once logged in, recent chats should show up as new conversations automatically. Other chats will get portals as you receive messages. - -You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html). - -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature diff --git a/docs/configuring-playbook-bridge-mautrix-instagram.md b/docs/configuring-playbook-bridge-mautrix-instagram.md index 0e16c7eba..deef0c346 100644 --- a/docs/configuring-playbook-bridge-mautrix-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-instagram.md @@ -1,10 +1,12 @@ # Setting up Mautrix Instagram bridging (optional, deprecated) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + **Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-instagram.md). Consider using that bridge instead of this one. The playbook can install and configure [mautrix-instagram](https://github.com/mautrix/instagram) for you. -See the project's [documentation](https://docs.mau.fi/bridges/python/instagram/index.html) to learn what it does and why it might be useful to you. +See the project's [documentation](https://github.com/mautrix/instagram/blob/master/README.md) to learn what it does and why it might be useful to you. ## Adjusting the playbook configuration @@ -14,33 +16,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_instagram_enabled: true ``` -There are some additional things you may wish to configure about the bridge before you continue. +### Extending the configuration -Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file: +There are some additional things you may wish to configure about the bridge. -```yaml -matrix_mautrix_instagram_configuration_extension_yaml: | - bridge: - encryption: - allow: true - default: true -``` - -If you would like to be able to administrate the bridge from your account it can be configured like this: - -```yaml -# The easy way. The specified Matrix user ID will be made an admin of all bridges -matrix_admin: "@alice:{{ matrix_domain }}" - -# OR: -# The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins. -matrix_mautrix_instagram_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -63,4 +43,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -Send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account. +You then need to send `login YOUR_INSTAGRAM_EMAIL_ADDRESS YOUR_INSTAGRAM_PASSWORD` to the bridge bot to enable bridging for your instagram/Messenger account. diff --git a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md index 6514cac90..b95fcfff2 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md @@ -1,7 +1,11 @@ # Setting up Instagram bridging via Mautrix Meta (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you. +See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you. + Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`). This documentation page only deals with the bridge's ability to bridge to Instagram. For bridging to Facebook/Messenger, see [Setting up Messenger bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-messenger.md). @@ -23,7 +27,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -35,37 +39,11 @@ matrix_mautrix_meta_instagram_enabled: true Before proceeding to [re-running the playbook](./installing.md), you may wish to adjust the configuration further. See below. -### Bridge permissions +### Extending the configuration -By default, any user on your homeserver will be able to use the bridge. +There are some additional things you may wish to configure about the bridge. -Different levels of permission can be granted to users: - -- `relay` - Allowed to be relayed through the bridge, no access to commands -- `user` - Use the bridge with puppeting -- `admin` - Use and administer the bridge - -The permissions are following the sequence: nothing < `relay` < `user` < `admin`. - -The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this: - -```yaml -matrix_mautrix_meta_instagram_bridge_permissions_default: - '*': relay - example.com: user - '{{ matrix_admin }}': admin -``` - -If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default. - -You may redefine `matrix_mautrix_meta_instagram_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_instagram_bridge_permissions_custom` like this: - -```yaml -matrix_mautrix_meta_instagram_bridge_permissions_custom: - '@alice:{{ matrix_domain }}': admin -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -88,24 +66,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@instagrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md index 9e40720bb..1890e6c27 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md @@ -1,7 +1,11 @@ # Setting up Messenger bridging via Mautrix Meta (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you. +See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you. + Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`). This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md). @@ -22,7 +26,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -48,37 +52,11 @@ You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variab Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.). -### Bridge permissions +### Extending the configuration -By default, any user on your homeserver will be able to use the bridge. +There are some additional things you may wish to configure about the bridge. -Different levels of permission can be granted to users: - -- `relay` - Allowed to be relayed through the bridge, no access to commands -- `user` - Use the bridge with puppeting -- `admin` - Use and administer the bridge - -The permissions are following the sequence: nothing < `relay` < `user` < `admin`. - -The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this: - -```yaml -matrix_mautrix_meta_messenger_bridge_permissions_default: - '*': relay - example.com: user - '{{ matrix_admin }}': admin -``` - -If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default. - -You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this: - -```yaml -matrix_mautrix_meta_messenger_bridge_permissions_custom: - '@alice:{{ matrix_domain }}': admin -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -101,28 +79,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`. -You then need to send a `login` command and follow the bridge bot's instructions. +You then need to send `login` to the bridge bot and follow the instructions. Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html). -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index b925a2bc2..575646806 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/docs/configuring-playbook-bridge-mautrix-signal.md @@ -1,8 +1,10 @@ # Setting up Mautrix Signal bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-signal](https://github.com/mautrix/signal) for you. -See the project's [documentation](https://docs.mau.fi/bridges/python/signal/index.html) to learn what it does and why it might be useful to you. +See the project's [documentation](https://docs.mau.fi/bridges/go/signal/index.html) to learn what it does and why it might be useful to you. ## Prerequisites (optional) @@ -16,7 +18,7 @@ However, if you're [using an external Postgres server](configuring-playbook-exte If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -26,46 +28,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_signal_enabled: true ``` -There are some additional things you may wish to configure about the bridge before you continue. +### Extending the configuration -By default, any user on your homeserver will be able to use the bridge. +There are some additional things you may wish to configure about the bridge. -Different levels of permission can be granted to users: - -* relay - Allowed to be relayed through the bridge, no access to commands; -* user - Use the bridge with puppeting; -* admin - Use and administer the bridge. - -The permissions are following the sequence: nothing < relay < user < admin. - -The default permissions are set as follows: - -```yaml -permissions: - '*': relay - example.com: user -``` - -If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file: - -```yaml -matrix_mautrix_signal_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -This will add the admin permission to the specific user, while keeping the default permissions. - -In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file: - -```yaml -matrix_mautrix_signal_bridge_permissions: - '@alice:{{ matrix_domain }}': admin - '@bob:{{ matrix_domain }}' : user -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -88,24 +55,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@signalbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Signal` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/signal/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-slack.md b/docs/configuring-playbook-bridge-mautrix-slack.md index dd2ee5342..759020e56 100644 --- a/docs/configuring-playbook-bridge-mautrix-slack.md +++ b/docs/configuring-playbook-bridge-mautrix-slack.md @@ -1,5 +1,7 @@ # Setting up Mautrix Slack bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + **Note**: bridging to [Slack](https://slack.com/) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [matrix-appservice-slack](configuring-playbook-bridge-appservice-slack.md) bridges supported by the playbook. - For using as a Bot we recommend the [Appservice Slack](configuring-playbook-bridge-appservice-slack.md), because it supports plumbing. Note that it is not available for new installation unless you have already created a classic Slack application, because the creation of classic Slack applications, which this bridge makes use of, has been discontinued. - For personal use with a slack account we recommend the `mautrix-slack` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Slack bridges supported by the playbook. @@ -20,7 +22,7 @@ Note that neither of these methods are officially supported by Slack. [matrix-ap If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -30,16 +32,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_slack_enabled: true ``` -You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. +### Extending the configuration -### Additional configuration +There are some additional things you may wish to configure about the bridge. -There are some additional options you may wish to configure with the bridge. - -Take a look at: - -- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file -- `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -66,24 +64,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use 4. Now that you're logged in, you can send `help` to the bot to see the available commands. 5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication. -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index c48820b38..20500db2e 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -1,5 +1,7 @@ # Setting up Mautrix Telegram bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-telegram](https://github.com/mautrix/telegram) for you. See the project's [documentation](https://docs.mau.fi/bridges/python/telegram/index.html) to learn what it does and why it might be useful to you. @@ -14,7 +16,13 @@ To use the bridge, you'd need to obtain an API key from [https://my.telegram.org If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Notes**: + +- Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. + +- If you decided to enable Double Puppeting manually, send `login-matrix` to the bot in order to receive an instruction about how to send an access token to it. ## Adjusting the playbook configuration @@ -26,26 +34,7 @@ matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH ``` -## Installing - -After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: - - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start -``` - -**Notes**: - -- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account. - -- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` - - `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. - -## Usage - -To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). +### Relaying If you want to use the relay-bot feature ([relay bot documentation](https://docs.mau.fi/bridges/python/telegram/relay-bot.html)), which allows anonymous user to chat with telegram users, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: @@ -68,34 +57,40 @@ matrix_mautrix_telegram_configuration_extension_yaml: | More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410 -If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration: +### Use the bridge for direct chat only + +If you want to exclude all groups from syncing and use the Telegram-Bridge only for direct chats, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_mautrix_telegram_filter_mode: whitelist ``` -### 💡 Set up Double Puppeting +### Extending the configuration -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). +There are some additional things you may wish to configure about the bridge. -To set it up, you have 2 ways of going about it. + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. -#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth +## Installing -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. +After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start +``` -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. +**Notes**: -#### Method 2: manually, by asking each user to provide a working access token +- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account. -**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging. +- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: + `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). +## Usage -- send `login-matrix` to the bot and follow instructions about how to send the access token to it +To use the bridge, you need to start a chat with `@telegrambot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -- make sure you don't log out the `Mautrix-Telegram` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-twitter.md b/docs/configuring-playbook-bridge-mautrix-twitter.md index 81813d2d1..cf2a85f75 100644 --- a/docs/configuring-playbook-bridge-mautrix-twitter.md +++ b/docs/configuring-playbook-bridge-mautrix-twitter.md @@ -1,5 +1,7 @@ # Setting up Mautrix Twitter bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + **Note**: bridging to [Twitter](https://twitter.com/) can also happen via the [mx-puppet-twitter](configuring-playbook-bridge-mx-puppet-twitter.md) bridge supported by the playbook. The playbook can install and configure [mautrix-twitter](https://github.com/mautrix/twitter) for you. @@ -12,7 +14,7 @@ See the project's [documentation](https://github.com/mautrix/twitter/blob/master If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. ## Adjusting the playbook configuration @@ -22,6 +24,13 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_twitter_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: @@ -41,29 +50,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use ## Usage -1. You then need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -2. Send login-cookie to start the login. The bot should respond with instructions on how to proceed. +To use the bridge, you need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html). +You then need to send login-cookie to start the login. The bot should respond with instructions on how to proceed. -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service is configured and enabled on the server for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/twitter/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-whatsapp.md b/docs/configuring-playbook-bridge-mautrix-whatsapp.md index 2fa6e9914..257d53eae 100644 --- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md +++ b/docs/configuring-playbook-bridge-mautrix-whatsapp.md @@ -1,14 +1,20 @@ # Setting up Mautrix Whatsapp bridging (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-whatsapp](https://github.com/mautrix/whatsapp) for you. See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you. ## Prerequisite (optional) +### Enable Appservice Double Puppet or Shared Secret Auth + If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. -For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting) +See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting. + +**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future. ## Adjusting the playbook configuration @@ -20,19 +26,11 @@ matrix_mautrix_whatsapp_enabled: true Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks. -The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file: +### Extending the configuration -```yaml -matrix_mautrix_whatsapp_bridge_relay_enabled: true -``` +There are some additional things you may wish to configure about the bridge. -By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file: - -```yaml -matrix_mautrix_whatsapp_bridge_relay_admin_only: false -``` - -If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`. +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. ## Installing @@ -55,26 +53,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use To use the bridge, you need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -### 💡 Set up Double Puppeting - -After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). - -To set it up, you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Whatsapp` device some time in the future, as that would break the Double Puppeting feature +You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/whatsapp/authentication.html). diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index 9a057391e..02aa66fa6 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -1,5 +1,7 @@ # Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage (optional) +Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) + The playbook can install and configure [mautrix-wsproxy](https://github.com/mautrix/wsproxy) for you. See the project's [documentation](https://github.com/mautrix/wsproxy/blob/master/README.md) to learn what it does and why it might be useful to you. @@ -20,6 +22,12 @@ matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge' Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device. +### Extending the configuration + +There are some additional things you may wish to configure about the bridge. + +See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc. + ### Adjusting the wsproxy URL By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).