Merge pull request #4042 from luixxiul/fix

Update docs to add the common section "Troubleshooting"

docs/configuring-playbook-bot-matrix-registration-bot.md

@@ -75,7 +75,7 @@ just run-tags bot-matrix-registration-bot-clean-cache
 
 ## Troubleshooting
 
-As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-registration-bot`.
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-matrix-registration-bot`.
 
 ### Increase logging verbosity
 

docs/configuring-playbook-bridge-appservice-webhooks.md

@@ -14,9 +14,6 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_appservice_webhooks_enabled: true
 matrix_appservice_webhooks_api_secret: '<your_secret>'
 
-# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
-# matrix_appservice_webhooks_log_level: 'verbose'
-
 # As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
 # Note: This deprecated method is considered insecure.
 #

docs/configuring-playbook-bridge-hookshot.md

@@ -146,7 +146,7 @@ If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge
 
 ## Troubleshooting
 
-As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bridge-hookshot`.
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-hookshot`.
 
 ### Increase logging verbosity
 

docs/configuring-playbook-bridge-mautrix-discord.md

@@ -71,3 +71,16 @@ If you'd like to bridge guilds, send `guilds status` to see the list of guilds,
 After bridging, spaces will be created automatically, and rooms will be created if necessary when messages are received. You can also pass `--entire` to the bridge command to immediately create all rooms.
 
 If you want to manually bridge channels, invite the bot to the room you want to bridge, and run `!discord bridge CHANNEL_ID_HERE` to bridge the room. Make sure to replace `CHANNEL_ID_HERE` with the channel's ID.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-discord`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_discord_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-facebook.md

@@ -59,6 +59,16 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
 
 ## Troubleshooting
 
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-facebook`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_mautrix_facebook_logging_level: DEBUG
+```
+
 ### Facebook rejecting login attempts and forcing you to change password
 
 If your Matrix server is in a wildly different location than where you usually use your Facebook account from, the bridge's login attempts may be outright rejected by Facebook. Along with that, Facebook may even force you to change the account's password.

docs/configuring-playbook-bridge-mautrix-gmessages.md

@@ -53,3 +53,16 @@ To use the bridge, you need to start a chat with `@gmessagesbot:example.com` (wh
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/gmessages/authentication.html).
 
 After logging in, the bridge will create portal rooms for recent chats.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-gmessages`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_gmessages_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-googlechat.md

@@ -55,3 +55,15 @@ To use the bridge, you need to start a chat with `@googlechatbot:example.com` (w
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html).
 
 After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-googlechat`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_mautrix_googlechat_logging_level: DEBUG
+```

docs/configuring-playbook-bridge-mautrix-instagram.md

@@ -44,3 +44,15 @@ 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).
 
 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.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-instagram`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_mautrix_instagram_logging_level: DEBUG
+```

docs/configuring-playbook-bridge-mautrix-meta-instagram.md

@@ -69,3 +69,16 @@ To use the bridge, you need to start a chat with `@instagrambot:example.com` (wh
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
 
 After logging in, the bridge will sync recent chats.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-meta-instagram`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_mautrix_meta_instagram_logging_min_level: debug
+```

docs/configuring-playbook-bridge-mautrix-meta-messenger.md

@@ -84,3 +84,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 After logging in, the bridge will sync recent chats.
 
 **Note**: 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.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-meta-messenger`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# This bridge uses zerolog, so valid levels are: panic, fatal, error, warn, info, debug, trace
+matrix_mautrix_meta_messenger_logging_min_level: debug
+```

docs/configuring-playbook-bridge-mautrix-signal.md

@@ -60,3 +60,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 After logging in, the bridge will bridge chats as you receive messages.
 
 **Note**: Signal does not support any kind of message history (even on official apps), so the bridge won't backfill any messages.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-signal`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_signal_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-slack.md

@@ -63,3 +63,16 @@ To use the bridge, you need to start a chat with `@slackbot:example.com` (where
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/slack/authentication.html).
 
 If you authenticated using a token, the recent chats will be bridged automatically (depending on the `conversation_count` setting). Otherwise (i.e. logging with the Discord application), the chats the bot is in will be bridged automatically.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-slack`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_slack_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-telegram.md

@@ -93,3 +93,15 @@ To use the bridge, you need to start a chat with `@telegrambot:example.com` (whe
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/telegram/authentication.html).
 
 After logging in, the bridge will create portal rooms for all of your Telegram groups and invite you to them. Note that the bridge won't automatically create rooms for private chats.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-telegram`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `WARNING`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+matrix_mautrix_telegram_logging_level: DEBUG
+```

docs/configuring-playbook-bridge-mautrix-twitter.md

@@ -55,3 +55,16 @@ To use the bridge, you need to start a chat with `@twitterbot:example.com` (wher
 You can then follow instructions on the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/twitter/authentication.html).
 
 After logging in, the bridge will create portal rooms for some recent chats. Portal rooms for other chats will be created as you receive messages.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-twitter`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_twitter_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-whatsapp.md

@@ -56,3 +56,16 @@ You can then follow instructions on the bridge's [official documentation on Auth
 Approximately in a minute after logging in, the bridge will create portal rooms for recent chats.
 
 **Note**: your linked devices will be logged out if you don’t use your phone for over 14 days (see the official FAQ entry [here](https://faq.whatsapp.com/general/download-and-installation/about-linked-devices)). The bridge will warn you if it doesn't receive any data from the phone over 12 days.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-whatsapp`.
+
+### Increase logging verbosity
+
+The default logging level for this component is `warn`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook:
+
+```yaml
+# Valid values: fatal, error, warn, info, debug, trace
+matrix_mautrix_whatsapp_logging_level: 'debug'
+```

docs/configuring-playbook-bridge-mautrix-wsproxy.md

@@ -67,3 +67,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 ## Usage
 
 Follow the [mautrix-imessage documenation](https://docs.mau.fi/bridges/go/imessage/index.html) for running `android-sms` and/or `matrix-imessage` on your device(s).
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-mautrix-wsproxy`.

docs/configuring-playbook-bridge-wechat.md

@@ -47,7 +47,7 @@ Send `help` to the bot to see the available commands.
 
 ## Troubleshooting
 
-As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bridge-wechat`.
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-wechat`.
 
 ### Increase logging verbosity
 

docs/configuring-playbook-jitsi.md

@@ -382,6 +382,12 @@ ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --ta
 
 ## Troubleshooting
 
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running the commands below:
+- `journalctl -fu matrix-jitsi-web`
+- `journalctl -fu matrix-jitsi-prosody`
+- `journalctl -fu matrix-jitsi-jicofo`
+- `journalctl -fu matrix-jitsi-jvb`
+
 ### `Error: Account creation/modification not supported`
 
 If you get an error like `Error: Account creation/modification not supported` with authentication enabled, it's likely that you had previously installed Jitsi without auth/guest support.

docs/configuring-playbook-postgres-backup.md

@@ -36,3 +36,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
 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. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-postgres-backup`.

docs/configuring-playbook-prometheus-grafana.md

@@ -155,6 +155,12 @@ scrape_configs:
           index: 18111
 ```
 
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running the commands below:
+- `journalctl -fu matrix-prometheus` for Prometheus
+- `journalctl -fu matrix-grafana` for Grafana
+
 ## More information
 
 - [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)

docs/configuring-playbook-s3-goofys.md

@@ -124,3 +124,7 @@ After making the backup, follow one of the guides below for a migration path fro
 7. You're done! Verify that loading existing (old) media files works and that you can upload new ones.
 
 8. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-goofys`.

roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml

@@ -118,7 +118,7 @@ matrix_mautrix_discord_appservice_bot_avatar: mxc://maunium.net/nIdEykemnwdisvHb
 matrix_mautrix_discord_provisioning_shared_secret: disable
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_discord_logging_level: 'warn'
 
 # Whether or not created rooms should have federation enabled.

roles/custom/matrix-bridge-mautrix-gmessages/defaults/main.yml

@@ -86,7 +86,7 @@ matrix_mautrix_gmessages_homeserver_token: ''
 matrix_mautrix_gmessages_appservice_bot_username: gmessagesbot
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_gmessages_logging_level: 'warn'
 
 # Whether or not created rooms should have federation enabled.

roles/custom/matrix-bridge-mautrix-signal/defaults/main.yml

@@ -93,7 +93,7 @@ matrix_mautrix_signal_homeserver_token: ''
 matrix_mautrix_signal_appservice_bot_username: signalbot
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_signal_logging_level: 'warn'
 
 # Whether or not created rooms should have federation enabled.

roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml

@@ -62,7 +62,7 @@ matrix_mautrix_slack_backfill_unread_hours_threshold: 720
 matrix_mautrix_slack_backfill_threads_max_initial_messages: 50
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_slack_logging_level: 'warn'
 
 # Database-related configuration fields.

roles/custom/matrix-bridge-mautrix-twitter/defaults/main.yml

@@ -130,7 +130,7 @@ matrix_mautrix_twitter_backfill_max_catchup_messages: 500
 matrix_mautrix_twitter_provisioning_shared_secret: disable
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_twitter_logging_level: 'warn'
 
 # Whether or not metrics endpoint should be enabled.

roles/custom/matrix-bridge-mautrix-whatsapp/defaults/main.yml

@@ -82,7 +82,7 @@ matrix_mautrix_whatsapp_homeserver_token: ''
 matrix_mautrix_whatsapp_appservice_bot_username: whatsappbot
 
 # Minimum severity of journal log messages.
-# Options: trace, debug, info, warn, error, fatal
+# Valid values: fatal, error, warn, info, debug, trace
 matrix_mautrix_whatsapp_logging_level: 'warn'
 
 # Whether or not created rooms should have federation enabled.