Last updated: 04 MAR 2019 by @seanvree

Please read the Methodology Wiki before proceeding

a. Browser compatibility: The only known issues with any browsers while viewing the main UI (index.php or index.min.php) is IE/Edge. Some CSS properties are not compatible in IE/Edge, therefore some elements may be disoriented. All other browsers are compatible.

b. The Monitorr settings page is NOT designed for mobile. Depending on your device it may or may not work. See issue: https://github.com/Monitorr/Monitorr/issues/175

c. Webserver Authentication. Monitorr uses CURL to check if services are accessible via anonymous requests. Depending on your webserver's configuration relating to return codes for auth...this will affect how CURL reports back to the Monitorr UI for the status. We are adding an option for authentication soon. Projected roll-out: TBD

d. Windows & system stats. There are few options to parse system stats on windows via PHP. Some work natively, some do not. We use several UNIX based commands to retrieve system stats. Because of this, it is highly recommended to install GIT. Please see the Initial Configuration section for further instructions. In addition, despite having GIT installed, you might see the following "warnings" in your PHP logs. They are just that, a "warning" and can be safely ignored.

Notice: A non well formed numeric value encountered in C:\inetpub\wwwroot\monitorr\assets\php\functions.php on line 219 Notice:

e. RAM usage: macOS (Mojave) and Docker running on unRaid will NOT display the correct RAM usage. We are working on fix for this.

a. PHP errors: Ensure you have all the prerequisites listed in the CONFIG: Initial configuration wiki. To check if your webserver has all required PHP prerequisites, clone/download the repo to your webserver and browse to "[monitorr repo]/assets/php/phpinfo.php". If all prerequisites are enabled, you will see a page similar to what is pictured below. If a required extension is NOT enabled/installed, the badge will appear RED:

• A common issue is not having PHP ZipArchive installed. This will cause errors when attempting to update via the UI, as you might see errors such as this:

PHP message: PHP Fatal error:  Uncaught Error: Class 'ZipArchive' not found in /var/www/monitorr/assets/php/update-functions.php:22

PHP ZipArchive is included on all Windows PHP version, however, on Linux platforms you must install it with the below commands:

sudo apt-get install php7.0-zip
sudo phpenmod zip
sudo systemctl restart nginx

b. Ensure you have the latest version. The version number installed is at the bottom of the UI in the footer area, or in the file at [Monitorr install path]/assets/js/version/version.txt

c. If you recently updated versions, clear your browser cache.

d. If you have manually edited the Monitorr code in any way, this can prevent the update process from pushing changes to your local repo.

e. Ensure you can access the exact same link you provided in your config file from the server which Monitorr is being served from.

f. System stats show a NULL/or improper values on Windows hosts: Install GIT. See https://github.com/Monitorr/Monitorr/wiki/01-Config:--Initial-configuration

g. Ensure ALL Monitorr services are in the following format:

<protocol>://<domain/IP>:<port>/<baseURL(if required)>

Example: https://google.com:443

NOTE1: If you see the error below in the UI, this means that an improperly formatted URL exists in the "Services Configuration" page.

NOTE2: If you are monitoring a service which is reverse proxied via your webserver, the PORT would be your EXTERNAL webserver port ie, http://yourdomain.com:80/PLEX

a. PHP 7.1+ is highly recommended, although Monitorr should work on PHP 5x (excluding macOS).

b. If you cannot access the Monitorr UI at all (which are normally 500 errors), check to see if your webserver is running PHP correctly. To do this, browse to yourdomain.com/monitorr/assets/php/phpinfo.php . If this page fails to load, it is likely there are underlying PHP issues, which will prevent Monitorr from loading.

c. Enabling PHP error display:

• Editing your php.ini file to output errors to the browser is also VERY helpful to troubleshoot problems. You can do this by editing the php.ini file in your PHP installation directory. In the php.ini file, you will see the line below.

display_errors = Off

• Temporarily change it to:

display_errors = On

• Once you have made this change, reboot your webserver/PHP and browse to index.php, you should see errors in the Monitorr UI where the problems are occurring. The example below is displaying a PHP warning in the top right area where the system stats are displayed.

• If the Monitorr settings files in your data directory have been corrupted or lost, rename the file "datadir.json" in your local Monitorr installation directory at: /[monitorr repo location]/assets/data/datadir.json . Once this file has been renamed, you can then browse to the settings page and perform the registration process again. This will regenerate the three JSON files which contain your settings and a new user database file.

• If the settings page is not accessible, you can also attempt to browse to: /monitorr repo location/assets/config/_installation/_register.php

• If the credentials to the settings page need to be changed or reset do the following:

1. Rename the file in your data directory users.db to 'users.old'.
2. Browse to the Monitorr settings page again to establish a new user database. This will NOT overwrite your settings UNLESS you choose to establish a new "data directory".

NOTE1: Establishing a new user database will NOT overwrite your settings, the process is only needed when you need to reset the settings page login credentials.

NOTE1: The Username and Password are case sensitive.

NOTE2: If for some reason you want to reset ALL Monitorr settings, you can either use the registration tool and "Establish a new data directory", or rename the file: [monitorr repo location]/assets/data/datadir.json and then browse to the settings page where you'll be prompted to establish a new data directory and user database.

a. If you have edited the base code in any way and then update via the UI, GitHub or DockerHub, you MAY need to backup that custom file and replace with the updated file from the remote repo, then apply your changes to the updated file.

• If a service status is OFFLINE, Monitorr will display an alert banner like so:

• This function is triggered by the creation of a *.json file with the service name in the /assets/logs/ directory as "servicename.json" when the service is OFFLINE.

• When the service returns to an ONLINE or UNRESPONSIVE status, the .json file is renamed to “offline.json.old”. This will then trigger the UI to remove the alert banner. Note that this is not "real-time", as the alert banner update is added/removed according to your settings under "Service & System refresh interval" in addition to several seconds to allow for the log file to be updated. For example: if the refresh interval is set to 10000 (10 seconds), it MAY take up to ~15 seconds to actually remove the alert banner once the service is back ONLINE.

• If the alert banner is erroneously persistent in the UI, and the service is ONLINE, manually remove the .json file from the /assets/logs/ directory. If there are ANY *.json files in this directory, the alert banner will be visible.

NOTE: If more than one service is OFFLINE, the alert banner will display each service that is offline in the banner area via scrolling "marquee" method. The interval at which the marquee displays the services currently offline is defined by the "Service & system refresh interval" in the "Monitorr Settings" page.

a. If a service you have enabled does not serve a webpage, ensure it is configured for "Ping Only" in the "Check Type" area of Services Configuration. This will drastically improve loading times.

b. Monitorr checks timeout at a MAX of 10 seconds per service. So, if you have a service that is OFFLINE, this will slow loading time of the Monitorr UI. Knowing that, if you have a service that you expect to be down for a length of time, it's advisable to disable that service in the "Services Configuration".

c. Webserver Authentication - disable authentication for the problematic application to test if it responds to CURL requests, to rule out webserver rejections due to authentication. Monitorr is designed to report an ONLINE status (HTTP ~400) even if there is authentication enabled at the given URL. However, depending on how the web-server is configured, CURL may fail due to custom HTTP codes.

d. Add a public site as a service such as https://google.com:443 to see if curl is working properly.

e. Disable all services except for Google, and test to see if your web-server is executing CURL properly. If it is, re-enable your services individually to isolate the problematic service. If you are able to access the Monitorr UI, but ALL services you add show OFFLINE, this is usually an indication that you DO NOT have CURL installed, and/or PHP is not configured properly. In rare cases, A/V and firewall software can cause complications.

f. Base URLs: Depending on the service/app, you may need to add a base path to the URL after PORT (Example: (PlexPY): 127.0.0.1:32500 will report as DOWN, 127.0.0.1:32500/PLEXPY will report as UP). In addition, a trailing slash MAY have an effect on CURL depending on redirection, URL rewrite, etc.

g. Apps that are known to return an UNRESPONSIVE status in Monitorr:

• NETDATA (added 07 FEB 18) (see: https://github.com/Monitorr/Monitorr/issues/121)
• EMBY (added 04 APR 18) https://emby.media/community/index.php?/topic/41218-curl-api-http11-400-bad-request/
• DD-WRT
• NZBGet
• Mattermost (Fixed if running Mattermost 4.6.0 or later)
• Docker containers running on a windows host (see https://github.com/Monitorr/Monitorr/issues/111)

h. If you have a service that is reporting as UNRESPONSIVE due to CURL incompatibility, you can change the "Check Type" to "Ping Only" or a less advisable route is to change the Monitorr code to show it as ONLINE. This will simply make all the "unresponsive" results appear ONLINE. This work-around will still show when a service is OFFLINE.

change /assets/php/check.php around line 134 to this:

        // echo '<p class="btunknown">Unresponsive</p>';
        echo '<p class="btnonline">Online</p>';

a. To test a single service without using the Monitorr UI, edit the file in /assets/php/checkmanual.php and add the EXACT same URL you used in the "Check URL" field of the "Services Configuration" page and insert it in the checkmanual.php file where indicated near line 30:

    // INSERT URL TO CHECK BELOW: //

     $url = 'https://google.com:443';

     // INSERT URL TO CHECK ABOVE: //

b. After you have edited the checkmanual.php file, browse to that file in your browser, eg: http://yourdomain/monitorr/assets/php/checkmanual.php. The browser output will provide further details about why a particular service may be failing.

note1: Checking a service using this method CAN take up to 180 seconds. Let the script finish and/or time-out, there will be an error either in the browser, in the browser console, or the script will return an error.

note2: Before you browse to the checkmanual.php page in your browser, it is advised to launch your browser in "developer mode / console view" (F12) and watch for errors in the console output as the script runs.

note3: You MAY want to first test a known service like google to see how the output SHOULD appear.

c. If the above method does not work, you can conduct further testing via CLI. This is accomplished by running the following commands in a terminal ON THE SERVER that is hosting Monitorr. You will want to use the same exact address used in the "Services Configuration" settings page. You MAY need to add CURL to your environment variable PATH in order to execute the CURL command. Or you can download the CURL binary from here (Windows): https://curl.haxx.se/dlwiz/?type=bin&os=Win64&flav=-&ver=*&cpu=x86_64 and execute the curl.exe using the examples below:

curl -I -L http://192.168.1.1:80

You'll see the response below for particular service (in this case DDWRT) rejects the curl request. So despite the user being able to access that exact address from a browser, Monitorr would report this service as DOWN or Unresponsive. In this case, you should contact that application developer and ask why their application does not respond to CURL, there MAY be a perfectly good explanation.

Response:

C:\WINDOWS\system32>curl -I -L http://192.168.1.1
curl: (52) Empty reply from server

These are examples of successful CURL responses: (The below example is a response from PLEX, despite the response being "401 - unauth" the website IS responding, therefore Monitorr would report it as ONLINE.)

C:\WINDOWS\system32>curl -I -L localhost:32400
HTTP/1.1 401 Unauthorized
Content-Length: 193
Content-Type: text/html
X-Plex-Protocol: 1.0
Cache-Control: no-cache
Date: Thu, 04 Jan 2018 18:55:04 GMT

And below are normal successful responses:

C:\WINDOWS\system32>curl -I -L localhost:80
HTTP/1.1 301 Moved Permanently
Content-Length: 144
Content-Type: text/html; charset=UTF-8
Location: http://localhost/home
Server: Microsoft-IIS/10.0
 Access-Control-Allow-Origin: Access-Control-Allow-Origin: http://www.yourdomain.com
Date: Thu, 04 Jan 2018 18:55:15 GMT

HTTP/1.1 301 Moved Permanently
Content-Length: 145
Content-Type: text/html; charset=UTF-8
Location: http://localhost/home/
Server: Microsoft-IIS/10.0
 Access-Control-Allow-Origin: Access-Control-Allow-Origin: http://www.yourdomain.com
Date: Thu, 04 Jan 2018 18:55:15 GMT

HTTP/1.1 200 OK
Content-Length: 8118
Content-Type: text/html
Last-Modified: Wed, 27 Dec 2017 02:26:49 GMT
Accept-Ranges: bytes
ETag: "aea44b26ba7ed31:0"
Server: Microsoft-IIS/10.0
 Access-Control-Allow-Origin: Access-Control-Allow-Origin: http://www.yourdomain.com
Date: Thu, 04 Jan 2018 18:55:15 GMT