Updated Troubleshooting (markdown)

master
Chris Caron 2021-12-13 21:44:13 -05:00
parent 0e0710f98b
commit f71097a054
1 changed files with 16 additions and 0 deletions

@ -1,4 +1,16 @@
## Table of Contents
<!--ts-->
* [General Troubleshooting](#general-troubleshooting)
* [Tag Matching Issues](#tag-matching-issues)
* [Too Much Data and Overflow Directive](#too-much-data-and-overflow-directive)
* [Special Characters and URL Conflicts](#special-characters-and-url-conflicts)
* [Formatting Issues](#formatting-issues)
<!--te-->
## General Troubleshooting ## General Troubleshooting
The best thing you can do when troubleshooting problems with your notification is to work it out using the _apprise_ command line tool. You can add verbosity what is going on with the notification you're troubleshooting by simply specifying **-v**; the more v's you specify, the more verbose it gets: The best thing you can do when troubleshooting problems with your notification is to work it out using the _apprise_ command line tool. You can add verbosity what is going on with the notification you're troubleshooting by simply specifying **-v**; the more v's you specify, the more verbose it gets:
```bash ```bash
# In the below example, I am trying to figure out why my mailto:// line # In the below example, I am trying to figure out why my mailto:// line
@ -15,6 +27,7 @@ Please feel free to join us on [Discord](https://discord.gg/MMPeN2D); it's not a
Just be cautious as the debugging information can potentially expose personal information (such as your password and/or private access tokens) to the screen. Please remember to erase this or swap it with some random characters before posting such a thing publicly. Just be cautious as the debugging information can potentially expose personal information (such as your password and/or private access tokens) to the screen. Please remember to erase this or swap it with some random characters before posting such a thing publicly.
## Tag Matching Issues ## Tag Matching Issues
If you tagged your URLs, they're not going to be notified unless you explicitly reference them with **--tag=** (or **-g**). You can always check to see what URLs have been loaded using the `all` tag directive paired with **--dry-run**: If you tagged your URLs, they're not going to be notified unless you explicitly reference them with **--tag=** (or **-g**). You can always check to see what URLs have been loaded using the `all` tag directive paired with **--dry-run**:
```bash ```bash
# This simply lists all of the tags found in the apprise.txt file # This simply lists all of the tags found in the apprise.txt file
@ -36,6 +49,7 @@ python apprise --dry-run --tag=devops \
``` ```
## Too Much Data and Overflow Directive ## Too Much Data and Overflow Directive
Out of the box, Apprise passes the full message (and title) you provide right along to the notification source(s). Some sources can handle a large surplus of data while others might not. These limitations are documented (*to the best of my knowledge*) on each of the [individual services corresponding wiki pages](https://github.com/caronc/apprise/wiki#notification-services). Out of the box, Apprise passes the full message (and title) you provide right along to the notification source(s). Some sources can handle a large surplus of data while others might not. These limitations are documented (*to the best of my knowledge*) on each of the [individual services corresponding wiki pages](https://github.com/caronc/apprise/wiki#notification-services).
However if you don't want to be bothered with upstream restrictions, Apprise has a somewhat _non-elegant_ way of handling these kinds of situations that you can leverage. You simply need to tack on the **overflow** parameter somewhere in your Apprise URL; for example: However if you don't want to be bothered with upstream restrictions, Apprise has a somewhat _non-elegant_ way of handling these kinds of situations that you can leverage. You simply need to tack on the **overflow** parameter somewhere in your Apprise URL; for example:
@ -60,6 +74,7 @@ Please note that the **overflow=** option isn't a perfect solution:
So while the overflow _switch_ is a viable solution for most notification services; consider that it may not work perfectly for all. So while the overflow _switch_ is a viable solution for most notification services; consider that it may not work perfectly for all.
## Special Characters and URL Conflicts ## Special Characters and URL Conflicts
Apprise is built around URLs. Unfortunately URLs have pre-reserved characters it uses as delimiters that help distinguish one argument/setting from another. Apprise is built around URLs. Unfortunately URLs have pre-reserved characters it uses as delimiters that help distinguish one argument/setting from another.
For example, in a URL, the **&**, **/**, and **%** all have extremely different meanings and if they also reside in your password or user-name, they can cause quite a troubleshooting mess as to why your notifications aren't working. For example, in a URL, the **&**, **/**, and **%** all have extremely different meanings and if they also reside in your password or user-name, they can cause quite a troubleshooting mess as to why your notifications aren't working.
@ -82,6 +97,7 @@ Below is a chart of special characters and the value you should set them:
| **:** | **%3A** | A colon will never need to be escaped unless it is found as part of a user/pass combination. Hence in a url `http://user:pass@host` you can see that a colon is already used to separate the _username_ from the _password_. Thus if your _{user}_ actually has a colon in it, it can confuse the parser into treating what follows as a password (and not the remaining of your username). This is a very rare case as most systems don't allow a colon in a username field. | **:** | **%3A** | A colon will never need to be escaped unless it is found as part of a user/pass combination. Hence in a url `http://user:pass@host` you can see that a colon is already used to separate the _username_ from the _password_. Thus if your _{user}_ actually has a colon in it, it can confuse the parser into treating what follows as a password (and not the remaining of your username). This is a very rare case as most systems don't allow a colon in a username field.
## Formatting Issues ## Formatting Issues
If your upstream server is not correctly interpreting the information you're passing it, it could be a simple tweak to Apprise you need to make to help it along. If your upstream server is not correctly interpreting the information you're passing it, it could be a simple tweak to Apprise you need to make to help it along.
The thing with Apprise is it doesn't know what you're feeding it (the format the text is in); so by default it just passes exactly what you hand it right along to the upstream service. Since Email operates using HTML formatting (by default), if you feed it raw text, it may not interpret the new lines correctly (because HTML ignores these charaters); you can solve this problem by 3 ways: The thing with Apprise is it doesn't know what you're feeding it (the format the text is in); so by default it just passes exactly what you hand it right along to the upstream service. Since Email operates using HTML formatting (by default), if you feed it raw text, it may not interpret the new lines correctly (because HTML ignores these charaters); you can solve this problem by 3 ways: