zmNinja FAQ
What is the minimum supported version of ZoneMinder, Android and iOS?
You need a minimum of ZM 1.32 with APIs working. You may get it to run in previous versions, but I don’t support them, so you are on your own.
zmNinja is supported only on IOS 11+ and Android 5.0+
zmNinja Help
All screens have annotated descriptions now. They are maintained in a google document, so I can easily edit it in future. Click here for the document.
Asking for refunds
For iOS: To get a refund, Apple wants you to contact them directly using this link. There used to be a time when I could process a refund myself, but it seems Apple doesn’t provide that interface anymore.
For Android: If you’re not happy with zmNinja and have bought the app, please send me an email with your order id.
Note that depending on how long ago you made the order, I may not be able to refund. Its not my policy - The app/play stores disable the refund option. For example, I could not refund an app a user purchased 2 years ago.
Also, please read Things you should own up to
Asking for apks
Updated Jun 2021: Please read this end of life notice
Every once in a while, I get a request from folks asking for the zmNinja APK. Usually, it is because their devices don’t have Google Play Store. And almost always, they offer to pay, just not via Google’s Play store.
I’m sorry, I don’t offer a non play store APK download mechanism. This is why:
The moment someone pays for the apk, there is an expectation that the app will be updated as well. If you get the apk from me, it will be frozen in time. And I don’t have the ability to supply updated apks on a regular basis. I know some of you think you will never need an update, but you will. Your OS may change, ZM may change and suddenly the app may have issues.
Technically, I suppose I could implement a different licensing server mechanism but that is exactly what the play store already provides. The reason I chose to use the play store is to avoid all of this. Goes back to how I prefer to use my available time.
The corollary to that is, as you know, the source code is on github and so are the build instructions. You are free to compile on your own to make your apk.
So bottom line, your reasons are likely very legitimate, just that I can’t support a non play store channel given my lack of available time.
Things you should own up to
Read the app description
Both the Apple and Android stores have a clearly visible note on the app description that it requires a working API for ZoneMinder. If you are not willing to ensure the API works, please save yourself and me time. I’m sorry this is the first post, but I get emails from too many entitled/rude folks about APIs not working. Not my problem. Read below. Breathe.
Try before buy
Some users legitimately look around for an option to try before they buy and they are not savvy enough to download the code and compile (Building from Source) for themselves. Fair enough. In that case, download the Desktop version of zmNinja. It’s free and is the same code as mobile. Make sure the desktop version works before you buy the mobile version.
The reason I don’t have a “trial mobile version” is that I find the process too complex using in-app-purchases and chose not to do it to make life simpler for me. As a substitute, I do make the full code available for free and offer a desktop binary version free too.
zmNinja doesn’t work. Actually, even ZoneMinder web console doesn’t work. You should fix this!
Yeah, look - I understand zmNinja won’t work if ZoneMinder web console doesn’t work. If you can’t set up ZoneMinder properly, please post your questions in the ZM forum. You’ll find qualified people to help you.
I can’t compile zmNinja, help me!
I put out the source code, so people who know how to compile are able to do it themselves. I also hope this will encourage folks to PR changes (though this has rarely happened). The problem however, is that dependencies/libraries keep changing. I just don’t have the time to help debug. If it happens to me, I’ll fix it. If it doesn’t I have very limited time to remotely debug your setup issues. I’d much appreciate if you figured it out on your own. Feel free to create an issue after you’ve tried enough, but I can’t guarantee I’ll spend a lot of time on source code compile issues.
How to report errors
I (pliablepixels) am no longer providing support for zmNinja. The code has been moved to Zoneminder and it is upto the devs or the community to continue support
In general, please try and localize the logs. It helps pinpoint the issue. Let’s assume you have an issue where montage always shows green dots instead of images. I’d recommend the following steps:
Load up zmNinja
Clear zmNinja logs
Kill the app
Load up zmNinja again and go to montage. I presume you are now looking at the error
Go to logs, and email them to me via the email button on top (envelope icon)
Specifically, don’t do a whole bunch of unrelated things and send me logs expecting me to sift through and find out what is going on.
I don’t know why something is not working if you don’t provide sufficient inputs. Start by creating a GitHub issue and please fill in the template correctly.
If zmNinja was working, but it stopped after you upgraded ZoneMinder be sure to mention which version was working and which was not. In this case, please make sure you have validated the APIs work
Before you create an issue, please make sure you have read the sections on connection issues and streaming issues and Step 6 of Validating APIs
Its often hard to infer a problem especially when its due to some unique apache/nginx mungling you might have done but haven’t told me about it. In such cases, try and give me remote access to your ZM for a day. Configure a limited user with just one monitor. It will save hours of frustration (mostly on my side). Thanks
I have released the desktop version free - download it here. Its always easier to debug on the desktop version - give it a try. If you hit Shift+Cmd/Ctrl+D it brings up a debug window - it helps debugging
Always tell me what your ZoneMinder & zmNinja versions are
If your app suddenly stopped working:
Send me DEBUG logs of the app
tell me what changed (got to be something. You updated the app, you upgraded ZM)
What exactly is not working?
If zmNinja does not start on your device
In this case, I’ll need logs.
Case 1: The app does work, but it got stuck and you can’t get out
In this case, it is easier to extract logs. If you are using Android, use one of the many free android file explorer applications (google for it and install the one that works for you) and extract the log file (zmNinjaLog.txt
). A common place for it to reside is in /data/data/com.pliablepixels.zmninja_pro/files
. If you are using iOS, you can use an app like IExplorer to connect to your phone. The app is paid for, but the demo license works just fine to extract the logs. In my case, logs were in Apps->zmNinja->Library->NoCloud->zmNinjaLog.txt
Case 2: The app doesn’t work at all and it gets stuck on the splash screen
There are some odd cases, where zmNinja does not start (or gets stuck in the splash screen) on specific devices. It is very hard for me to know why it fails on certain devices, but I can try. Here is what you need to do:
You have to look at the device system logs. To get system logs:
You will have to install
adb
(Android Debug Bridge). This XDA post describes the process of downloading and installing the tools.Once ADB is installed, connect the phone to the browser (make sure you have allowed debugging on the phone menu - it should ask) and type in
adb logcat >result.txt
and try to start the app. A lot of logs will be generated.Note that to just filter out zmNinja logs, you can use
adb logcat | grep "filelogger.min.js"
Study them and you’ll see more details
For iOS, use the method described in Case 1 above.
Connection/Authentication issues
General tips
Important
Make sure you have the following settings in ZM:
AUTH_RELAY
is set to hashedA valid
AUTH_HASH_SECRET
is provided (not empty)AUTH_HASH_IPS
is disabledOPT_USE_APIS
is enabledIf you are using any version lower than ZM 1.34,
OPT_USE_GOOG_RECAPTCHA
is disabledIf you are NOT using authentication at all in ZM, that is
OPT_USE_AUTH
is disabled, then make sure you also disable authentication in zmNinja, otherwise it will keep waiting for auth keys.I don’t quite know why, but on some devices, connection issues are caused because ZoneMinder’s CSRF code causes issues. See this thread, for example. In this case, try turning off CSRF checks by going to
ZM->Options->System
and disable “Enable CSRF magic”. You will then have to delete zmNinja’s API cache (Menu->Clear API Cache
) and restart the app.
Disable server redirects like 302 and then try if using the mobile app
To make sure there are no connection issues, launch your phone browser and try to reach ZoneMinder. If that doesn’t work, neither will zmNinja. Many users try to access ZoneMinder from a desktop browser and/or on the same server it is running and forget the phone is a different device!
Some phones need the SSL certificate installed in the device
Specific SSL settings can cause issues with Android or iOS
Don’t use funky/special characters in passwords - try changing it to a complex password without funky characters and try again
Use the wizard - I’ve seen many examples of typos when the user thinks they don’t have a typo
If you are using basic authentication, make sure your credentials are correct. A good way to test is to first disable basic auth and enable it after you are sure things work without basic auth.
Please note zmNinja does NOT support Digest authentication. So please don’t put in digest auth info when zmNinja asks for basic authentication
Look at your ZM logs and zmNinja logs - they help isolate the problem
Server Redirects
If the Wizard fails to connect in the mobile app but works in the
desktop app, it may be that your server is sending redirects.
Unfortunately, the current mobile HTTP stack doesn’t handle cookies with
redirects well. Till this bug is fixed by the plugin author Wizard won’t
work. Note that if you are running ZM 1.32 or above, you can directly
enter your settings without using the wizard and it will work because it
will try and use the new ZM 1.32 login.json
API first.
Self signed certs
A lot of people use self-signed certs. I’d strongly recommend you use LetsEncrypt if you can. It’s free. That being said zmNinja does support self signed certs. Make sure “Enable Strict SSL” is off in Developer settings. You will need to restart the app.
SSL settings
If you are getting SSL protocol/handshake errors
in your logs, you
very likely have specific ssl settings enabled server side that your
device network stack does not support. Note that just because it works
with the device browser does not mean it will work with zmNinja as
zmNinja does not use the browser HTTP implementation in mobile devices.
One use reported that a setting of ssl_ecdh_curve secp384r1
in his
nginx config was resulting in zmNinja Android not being able to connect
to the server. Changing it to
ssl_ecdh_curve secp521r1:secp384r1:prime256v1;
worked for him.
I’d strongly recommend you remove all special ssl settings except the certificate and key file locations, make it work and then add the settings back one by one and see what works/does not work.
Everything works when I use LAN IP, but I get “not authenticated” when I use WAN IP
This is likely happening if you use self signed SSL certs. If you are using self signed certificated, you should make sure the “common name” matches the hostname (or public IP) of the server you are installing ZM in. If not, zmNinja’s SSL handshake will fail.
If you have used ‘make-ssl-cert’ or a similar tool that automatically generates the cert for you, its very likely you have certificate that uses the ‘unix hostname’ of your server. That will not work.
Assuming you are usin apache and have SSL enabled, here is how to regenerate the certs (ubuntu specific, may need to tweak it for your distro)
This will create a self-signed certificate/key pair and store it in /etc/apache2/ssl (you may have to create that directory, or store it elsewhere)
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/zoneminder.key -out /etc/apache2/ssl/zoneminder.crt
Next up, edit your apache ssl config (example /etc/apache2/sites-available/default-ssl.conf) And add/modify the following lines:
SSLCertificateFile /etc/apache2/ssl/zoneminder.crt
SSLCertificateKeyFile /etc/apache2/ssl/zoneminder.key
restart apache
sudo service apache2 restart
Live streaming issues
Summary of Everything works, but I can’t see live feed
Please be diligent in reviewing this list. You’d be surprised how many times I’ve had users tell me ‘they have checked this list’ only to find out later they skimmed details.
Always try with the free desktop version first. Enable debug view by hitting Ctrl/Cmd+Shift+D and you can see debug logs in the console view. I can’t emphasize enough how useful this is.
First test, load up Zoneminder console from the device you are running zmNinja on. Check to see if zoneminder console streaming works. If not, fix that first.
Please enable
AUTH_HASH_LOGINS
as well as setAUTH_RELAY
to “hashed” in ZoneMinderIf you are NOT using authentication in ZM, please turn OFF authentication in zmNinja too. If you don’t, zmNinja will keep waiting for an authentication token. If this is the cause, you will see a “waiting for authSession to have a value” log in your zmNinja logs.
Super Important: Your
cgi-bin
setting in zmNinja may be incorrect. Please run the wizard. There are times when the wizard can fail. In those cases, open up ZM web console, go to view the monitor and do an “Inspect Source” in the browser. That will show you the cgi-bin link that you can use in zmNinja. Special Note: Many people miss looking closely at cgi-bin. Your browser may show/cgi-bin/
while your zmNinja may be set to<domain>/zm/cgi-bin/
. So the solution here is to remove/zm
from zmNinja.
For example:
In the above case my zmNinja cgi-bin setting is
https://myserver:myport/zm/cgi-bin
If you are using multi-server, please make sure the user account has “System View” permissions. This is needed to get access to the server API. If zmNinja is unable to read the API, it will use the default portal URL, which may fail.
You think your APIs are working, but they are really not. If you open a browser and type in
https://yourserver/zm/api/monitors.json
and you see some text on top followed by monitor data, your APIs are not working. You need to search the forums and figure out how to get rid of that text.The phone/computer running zmNinja does not have access to your ZM server when using WAN. For example, many people test the web console on their LAN but test zmninja on a WAN connection
You are using Basic Authentication. See here
You have ‘multi-server’ configuration enabled and you have done it wrong. Go to ZM Web Console->Options->Servers - if you see any entries there and you don’t know what multi-server is, or you don’t use it, please disable multi-server. Also see here
When trying to view live images, look at your webserver error logs - example Apache’s
error.log
- see any image/jpg errors? That means you are missing librariesLook at zmNinja, ZoneMinder and web server error logs at the time of error - one of them should give more clues. Please send me all the logs if you ask for help
On certain devices, Zoneminder’s CSRF checks cause issues. Turn off CSRF in Zoneminder by going to
Options->System
and turn offENABLE_CSRF_MAGIC
Read the set of notes below
General note
To debug streaming notes, always try with the free desktop version
first. When trying to stream simultaneously look at the debug logs of
zmNinja (Ctrl/Cmd+Alt+D
in desktop build, console and/or network
tab) and your webserver error logs.
I can’t see stream: And I can’t see streams in ZoneMinder webconsole either
Check if streaming works in the web interface. If it does not work, zmNinja won’t work either. Fix ZM first
I can’t see streams: I use basic auth
Starting Chrome v59, the browser changed basic credential behavior. The
issue report is
here.
Here is the core issue: zmNinja constructs URLs as
http://user:password@server
when you have basic auth (and starting
v1.3 uses the Authorization
header). However, since images are
rendered using <img src>
there is no option but to put in a
user:password
in the URL. Chrome allows this format for direct
requests (such as API calls) but will strip out the user:password
part for embedded requests (like <img src="">
tags inside a page).
So what happens is your APIs work, but you won’t see images. There is a
reason why Chrome does this - its bad to pass on a user :password in a
URL as its clear text (even if you are on HTTPS, as its in the URL). As
I said earlier, The right way to do this is to replace the
user:pass
with an Authorization
header but there is no way to do
that with images that are rendered with <img src>
(There are several
plugins that attempt to do this, but don’t work with streaming MJPEG
images). Bottom line, this is a problem for apps like zmNinja and it
affects you.
How this affects you: - If you are using HTTP Basic Authentication then your images won’t show.
Possible Workarounds:
- Configure your web server to skip basic authentication for nph-zms
URLs
- If you are using a ReverseProxy, you can insert the authorization header inside the apache proxy
- Disable HTTP Basic auth for now
- Downgrade Chrome (but this may no longer be an option, Chrome will not revert to the old behavior any more)
Skipping auth for nph-zms
URLs
Here is what I’ve used that works with basic-auth. This requires a basic auth portal login and once logged in allows skipping of image URLs (the idea comes from Adam Outler - he uses a different approach using reverse proxies, which I link to later)
# this configuration assumes your server portal is server:port/zm
# and cgi-path is /zm/cgi-bin. Please change it to your specific environment
# Also requires Apache 2.4 or above
<Location />
SetEnvIf Request_URI ^/zm/cgi-bin/ noauth=1
SetEnvIf Request_URI ^/zm/index.php noauth=1
AuthType Basic
AuthName "Auth Required"
AuthUserFile "/etc/apache2/.htpasswd"
<RequireAny>
Require valid-user
Require env noauth
</RequireAny>
</Location>
I can’t see streams: Multi-server is enabled
The chances are very high that you have enabled ZoneMinder’s
Multi-Server
option and you entered something like localhost
in server settings.
DON’T. You can’t enter localhost. If you are not using multi-server,
remove any server settings. If you are using multi-server, you need to
put in a valid server IP or hostname, not localhost
. BTW, if you did
put in localhost
you will note that your ZM web console also won’t
work if you try to launch your browser on a different machine from where
ZM is running.
I can’t see streams: you have cgi-bin issues
Try to use the wizard. If it fails,
Go to zmNinja settings and fix your cgi-bin path. the automatic path that is filled in won’t work. Here is a hint, go to zoneminder->options->paths and check the value of the cgi-bin path - your zmNinja path will be “base path of your server” + cgi-bin path.
I can’t see some streams (some work): you have multi-server access issues
If you are in a situation where some live streams work and some don’t,
it is possible you are using multi-server. In this case, you need to make
sure the user account has “view” privileges for “System”. zmNinja uses the
/server.json
API to get multi-server data so it can figure out which IP:port
is used for streaming for that server. If it fails, it will fallback to the portal
URL which will likely be wrong.
zmNinja montage does not seem smooth - feeds seem a little delayed compared to ZM console
zmNinja does not use nph-zms
to display live feeds in montage. This
is because Chrome only allows a maximum of 6 connections per (sub)domain
which means you can’t have more than 6 active TCP connections to a
single domain at the same time. This also means that you can’t display
more than 6 monitors together. To avoid this, I use the zoneminder
“snapshot” feature that displays a still from the monitor and then
refresh it every X seconds (by default X=2 unless you switch to low
bandwidth mode. You can change X in developer settings)
That being said, starting v1.3.0 of zmNinja onwards, I now support multi-port (available in ZM 1.32 onwards) that lets you stream as many monitors as you need. Read this post for more details.
Montage is killing my server
Remember, that by default, zmNinja montage streaming works differently from ZM’s web console. ZM’s web console uses
nph-zms
(The MJPEG streamer) to stream live views. The problem with this approach is you can’t see more than 6 monitors at the same time, on Chrome. Read the note just above this. The short therefore is if you want comparable performance, enable multiport as described above. As of today, zmNinja doesn’t have a way to use constant streaming if you have less than 6 monitors.Make sure you close your browsers (ZM web) when testing zmNinja, if load is an issue.
Reduce “Montage Image Scale” in developer settings and see if it helps
Enable “Disable Alarm API in Montage” in developer settings
Other misc. issues
APIs seem to work in the browser but zmNinja says APIs don’t work
There could be several reasons, but this one is common: look in the logs. If you see something like:
DEBUG **EXCEPTION**SyntaxError: Unexpected token < in JSON at position 0 caused by undefined.
Then that means the ZM API layer is throwing warning messages which you don’t see in your browser, but will show up
if you do an inspect source. The solution is to edit /usr/share/zoneminder/www/api/app/Config/core.php
(or whichever path your ZM is installed in) and around line 34-ish, you’ll see something like Configure::write('debug',2)
.
Change it to Configure::write('debug',0)
I suddently see an error message saying I need to enable ZM_AUTH_HASH_LOGINS. This wasn’t there before
Yes. Starting 1.3.027 onwards, due to a new UI web rendering engine that enforces CORS, I’ve had to change my strategy on how network calls are made. Briefly, on mobile devices, I now use a native HTTP stack and not the browser HTTP stack. However, images are rendered using the browser HTTP stack which causes this message. In short, you need to enable it, and restart ZM.
zmNinja 1.2.515 and beyond says “Need API Upgrade” for the 24hr review feature. What does that mean?
You need to update an API file in Zoneminder server. ZoneMinder folks
haven’t yet (as of Apr 2018) made a release with that API change. To do
it manually,simply replace your EventsController.php
(typically in
/usr/share/zoneminder/www/api/app/Controller
) with this
one.
I upgraded ZoneMinder to 1.30.2 or above and zmNinja stopped working!
ZoneMinder changed API packaging with ZM 1.30.2 and above. You will have to read your distro notes on how to properly update. Read this thread. Before you think zmNinja is the problem, make sure your APIs are working (see Validating APIs)
Summary of reasons why zmNinja might have stopped working: - You did not
check if your APIs are working after the upgrade - You did not upgrade
properly (just updating the ZM package without following distro
instructions with ZM is not sufficient) - You are missing some key
CakePHP modules, likely php5-apc
which would have been installed if
you read all the package instructions. You can install it manually - You
might need to restart your system after upgrading (properly)
I am running ZM on a custom port. zmNinja is unable to reach my ZoneMinder server but I tried on a regular browser (Firefox/Opera/IE) and it I can reach it
zmNinja on Android and Desktops uses an embedded chrome browser. Chrome marks certain ports as “unsafe” and won’t allow connections to go out. The list of ports to avoid are here
The Montage screen is causing issues with my ZM server - I get connection timeout issues or MySQL connection problems
zmNinja uses a different approach to display montage than ZoneMinder. In zmNinja montage screen, I display a snapshot of each monitor and refresh it every few seconds. This results in many short TCP connections constantly being opened and closed. The reason I have to do this is Chrome only allows 6 connections to a domain, which means if I don’t keep terminating TCP connections, I won’t be able to show more than 6 monitors. Each time I open a new TCP connection for a snapshot, the ZM backend invokes mySQL to authenticate the request. You will need to increase mySQL
max_connections
inmy.cnf
if you are facing time_wait/timeout issues.
The app works great - except it doesn’t work on ONE Android phone - works in others!
zmNinja uses an embedded chrome browser in its app. If you have safe browsing enabled, it may affect zmNinja. However, if you are facing this problem, its likely you can’t access ZM from a mobile web browser either. The problem that might be occurring is that zmNinja is trying to reach your ZM server and your settings prohibit it from reaching ZM, so it fails. See this discussion
APIs are not working ! ZM console works fine.
I’m using mocord/record and I don’t see events without alarms
Tap on the “…” menu option and toggle “Show all events”. By default, it shows events with at least one alarm frame
Taking snapshots or downloading videos don’t work in Android
If you are unable to download/save, look at your logs. If you see
something like
"exception":"java.security.cert.CertPathValidatorException: Trust anchor for certification path not found."
, chances are you are using self-signed certs. You need to install the
certificate on your phone. Installing is as easy as emailing yourself
the “.crt” file and tapping on it from your device to install it. In
general, both Apple and Google have been incrementally tightening rules
for self signed certificates - they generally discourage usage of such
certs and over time both Chrome (Android) and WkWebView (iOS) have added
new restrictions/checks which affects usage.
Pan/Tilt/Zoom doesn’t work
Tilt/Zoom/Presets support has not been added. But for this to work, PTZ needs to work in ZM first. Once it works in ZM, try it in ZMNinja. Also note that you may need to disable CSRF in your Options in ZoneMinder - it seems to cause all sorts of issues.
What is this Event Server?
The Event Server is a contribution I made to ZoneMinder that adds a daemon to the existing list. It listens for new events using shared memory (aka very efficient) and then sends notifications of events to listeners (you can write your own app that listen as well as use zmNinja). This is a chapter on its own, and I have a dedicated page/project for this here. I’d encourage you to install and use it - its very nice.
It looks like you allow me to modify the frequency of push notifications. Very cool - will it send me all events that I missed if I make the frequency of a monitor event push to say, 600 seconds?
Nope. It only sends the latest events. What it does is before sending push notifications, it checks if the last time a push was sent for this monitor is < the time you specified. If it is, it does not send. That’s all.
When I switch languages, date/time inputs don’t follow my locale in zmNinja Desktop
The only screen I am aware of where there is a date/time input is Events->Filter Events
. This happens because the desktop version uses an embedded chromium version which seems to default to en-us
. To work around this, you can start the desktop app with a --lang='<locale code>'
option. Example --lang='ru'
. Note that you will have to do this each time and is completely related to any language you may choose in zmNinja. Thel language in zmNinja is only used to translate text strings. Nothing else. For an extended discussion see this issue.
Is zmNinja free?
The source code is free, grab it, compile it, use it. The desktop ports are free as of today. I may charge for it some day. The mobile ports are in Appstore/Playstore for a fee.
Who are the developers behind this?
Originally the fabulous pliablepixels. Now the ZoneMinder developers try to keep it going.
The code needs improvement
You are being nice. I know the code is terrible. I’m not a coder by profession. This was my first project to learn how to write a mobile app. So the app evolved from no knowledge to some knowledge. It comprises of terrible to passable to reasonable code. There is a reason why my profile says what it says. But hey, if you can improve it, please PR!
Is zmNinja an official ZoneMinder product?
Originally no, but since pliablepixels has generously provided it to the ZoneMinder devs, it pretty much now is.
I want to donate money
Please see our donation page at <https://www.zoneminder.com/donate>
How does zmNinja use my personal data?
Please read this
I want to donate time/expertise/code
Great. Make sure you read the license , read the contributing guidelines and if it works for you, happy to see what you’d like to do.