Skip to content
This repository was archived by the owner on Jun 14, 2026. It is now read-only.

FAQ

Jump to bottom
Pliable Pixels edited this page Aug 15, 2018 · 141 revisions

zmNinja Help

I've just started uploading instructional videos for zmNinja. I'll add more over time. See them here

Asking for refunds

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

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 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. That being said, I really don't have time to help you debug ZoneMinder issues. I only develop the app (zmNinja). If you can't set up ZoneMinder properly, please post your questions in the ZM forum. You'll find more qualified people to help you. I don't develop nor control ZoneMinder. It's a different set of folks. Now, I'll help you, but only after you have spent sufficient time trying your best and provide sufficient logs of what you have done. Also remember, if you buy zmNinja, I'm happy to refund it anytime - just send me an email.

In short, I don't have the time to support ZoneMinder install issues - sorry about that

zmNinja doesn't work. Zoneminder works, but I have no idea why APIs don't work. You should fix this!

Sigh. I don't maintain ZoneMinder. I only develop the app. You need to make sure ZoneMinder APIs work. ZoneMinder web console doesn't use APIs. Neither does zmView. zmNinja does. It says so in the description of the app in the store. So feel free to fix your APIs, or ask me for a refund. Just don't whine to me, please, if your APIs are broken. I'm not going to fix them for you, especially if you act like its not your problem. I'm perfectly fine if you choose not to use my app, which is why I refund, anytime.

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'm not a magician. I don't know why something is not working if you don't provide sufficient inputs. Enable debug logs in zmNinja Developer options and then email me the logs. Thats a good start.
  • 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 Ctrl+Alt+D (or Cmd+Alt+D) it brings up a debug window - it helps debugging
  • Always tell me what your ZoneMinder version is
  • 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?

zmNinja is not saving my information. It keeps asking me to re-enter all my data

I've seen this happen in two cases:

  • You are running out of space. Clean up some space and try again
  • On specific Android devices, typically running Android OS less than 6.0, some (2-3) users have reported this issue. I still don't have a good answer. Please update to the latest app version and send me debug logs, please

Connection/Authentication Issues

  • Most of the issues I've seen so far are because zmNinja cannot reach ZoneMinder
  • To make sure there are no connection issues, launch your phone browser and try to reach ZoneMinder. If that doesn't work, neither with 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!
  • If you are using SSL, make sure you read the SSL section
  • Don't use funky/special characters in passwords - try changing it to a complex password without funky characters and try
  • Use the wizard - I've seen many examples of typos when the user thinks they don't have a typo
  • Look at your ZM logs and zmNinja logs - they help isolate the problem

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.

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.

  • Your ZoneMinder live view from the web console doesn't work either. If this is the case, fix ZoneMinder first
  • Your cgi-bin setting in zmNinja is incorrect. Please run the wizard
  • You are running zmNinja on Android and 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
  • 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 libraries
  • You have set up a multi-server install of ZM without knowing you did See here
  • Look 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
  • Read the set of notes below

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

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>

Authorization with a ReverseProxy

Simple Starter

STEP 1: Enable "Append basic auth tokens in images" option in zmNinja->Developer Settings and save. What this does is that image URLs will append a "basicauth" token parameter with your basic authentication credentials. This token can then be parsed by Apache and inserted as a valid Authorization header. Don't enable this option if you are not using HTTPS because the request-URI will be transmitted without encryption and it will contain your basic auth credentials, encoded in base64, which is trivial to decode.

STEP 2 (Apache): Use mod_rewrite and mod_header to convert the token into an authorization in your Apache config. Add this to the relevant section (VirtualHost or others)

     RewriteEngine on
     RewriteCond %{QUERY_STRING} (?:^|&)basicauth=([^&]+)
     RewriteRule (.*) - [E=QS_TOKEN:%1]
     RequestHeader set Authorization "Basic %{QS_TOKEN}e" env=QS_TOKEN

STEP 2 (Nginx): Thanks to user @ysammy

 location /zm/cgi-bin/nph-zms {
    proxy_pass http://<IP>:<PORT>/zm/cgi-bin/nph-zms;
    proxy_set_header Authorization "Basic $arg_basicauth";
  }
A more complete and more secure option

User Adam Outler has contributed the following process: see HERE. Adam also has this to say about why proxies should be recommended for HTTPS enabled ZoneMinder instances:

A proxy server should be on the list of recommendations for Zoneminder. HTTPS requires processing to encrypt and decrypt. This takes processor cycles away from Zoneminder's recording. Since HTTPS is now basically a requirement, there should be a page dedicated to proxy, https, auth, and their nuances. I just picked up 2-4K cameras and processing suddenly became an issue :).

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.

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 that lets you stream as many monitors as you need. As of April 2018, multiport is only available from Isaac Connor's Storage Area fork and is not part of mainstream Zoneminder, unfortunately. Read this post for more details. Note that thanks to a webkit bug, this feature won't be enabled for iOS devices.

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. 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 in my.cnf if you are facing time_wait/timeout issues.

Everything works! but event viewing does not work - I see question marks

  • Look at apache error logs - it often gives you hints
  • You don't have php5-gd installed (or php-gd, or libgd). You need this package. For ubuntu it's sudo apt-get install php5-gd. Make sure you restart apache.

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.

Read this

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

I use self signed certificates with SSL and zmNinja auth doesn't work! (works with http)

Starting release 1.0.6, you no longer need to install SSL certificates on the phone. If you are running a version less than 1.0.6 the stuff below applies:

For versions <1.0.6: Please read the SSL guide. Summary:

  • You need to make sure the common name used while generating the cert is the same as the hostname you specify in zmNinja
  • You need to make sure you import the SSL cert into your phone (if you are using the mobile app).

I have 20 monitors but zmNinja only shows 10

Go to developer settings - increase the limit.

zmNinja montage screen shows all my monitors, but in Event Montage, I only see 5?

You are likely using Chrome (Android or desktop version). Chrome allows a total of 6 simultaneous connections to a domain/sub-domain. ZoneMinder uses a long running TCP stream for each monitor display (keeps sending jpeg images). This means you can only display 6 streams at a time in Chrome. I work around this problem by not asking for live streams in montages - I ask for 'snapshots' and keep refreshing snapshots every 2 seconds. This makes montage display non-realtime, but scales to as many monitors you have. In Event Montage however, I am using zms to display long running streams - trying to do snapshots in event montage is a lot of work and I need to keep track of when the event ends, move to next image etc. I limit this to 5 because I need 1 for control messages.

It doesn't work

It does. If you need more help, please enable Debug Logs (Developer Settings) then please look at the logs and let me know what you see.

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

Downloading videos (if enable GIP/MP4 is on in dev settings) doesn't work in Android

If you are using self-signed certificates, 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.

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.

I am using your event server. I get push notifications to my desktop apps, but not my iPhone/Android phone

Both Apple and Android require that only trusted "servers" can push notifications to your phone. By "trusted", they mean the server needs to use the same SSL certificates that zmNinja uses. That way they can make sure only the author of the app can send the app messages. This makes a lot of sense, because otherwise anyone could spam your phone.

What this means is that you need to enable "usePushProxy" in the event server and have it point to my public push server. If you install the event server, this is enabled by default. If it is not working, check your ZM logs (not ZMNinja) to see if zmeventserver is complaining about anything

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.

Weird issue. I'm on Android. When I exit the app via the 'back key' or from the menu, I get a "the connection to the server was unsuccessful" error when I start the app again.

See this proposed workaround. I currently have no clue why that is occuring.

Is this 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?

Me.

Is zmNinja an official ZoneMinder product?

No. But the ZM developers are amazing people who have been very helpful.

I want to donate money

You could either donate to to Zoneminder or donate to zmNinja. Donations to ZoneMinder don't contribute to zmNinja, but the ZoneMinder devs will benefit from it, which is fine too.

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.

Clone this wiki locally