Configuring Zoneminder on Ubuntu 10.04

1) Target System:

Ubuntu 10.04 Desktop on Intel Dual Core E6400 PC. Capture card: Kodicom 4400 compatible, 4x BT878
I chose to install the desktop version instead of the server because it makes troubleshooting much easier.

The capture card can be checked directly on the target system. Often the basic capture card configuration is difficult, because the cheap clones do not have any EEPROM and can not be identified by the host system. Manual configuration is necessary.

2) Capture Card Installation

After installation of the capture card, each capture chip on the card should appear as a video device:

~$ ls -l /dev/video*
crw-rw----+ 1 root video 81, 0 2010-10-10 09:01 /dev/video0
crw-rw----+ 1 root video 81, 2 2010-10-10 09:01 /dev/video1
crw-rw----+ 1 root video 81, 4 2010-10-10 09:01 /dev/video2
crw-rw----+ 1 root video 81, 6 2010-10-10 09:01 /dev/video3

The video devices (=capture chips) are not related to the physical video inputs (e.g. BNC jacks). The video inputs are mapped to capture devices dynamically and SW controlled. One capture chip can capture a couple of video inputs by switching very fast between them. The max frame rate per capture chip will be divided between the served inputs. A bit of performance is lost because we have to synchronize to the video signal after each input switching.

If there are no video devices visible, check, if the capture card is recognized at all (see last lines containing "Bt878"):

~$ lspci
00:00.0 Host bridge: Intel Corporation 82G33/G31/P35/P31 Express DRAM Controller (rev 10)
00:02.0 VGA compatible controller: Intel Corporation 82G33/G31 Express Integrated Graphics Controller (rev 10)
00:1b.0 Audio device: Intel Corporation N10/ICH 7 Family High Definition Audio Controller (rev 01)
00:1c.0 PCI bridge: Intel Corporation N10/ICH 7 Family PCI Express Port 1 (rev 01)
.....
04:0f.0 Multimedia video controller: Brooktree Corporation Bt878 Video Capture (rev 11)
04:0f.1 Multimedia controller: Brooktree Corporation Bt878 Audio Capture (rev 11)

If there is no video controller visible on the PCI bus, there is probably a HW problem, maybe the capture card is faulty.

The capture chips can easily be recognized by Ubuntu. But the specific card type with tuner, multiplexer between video inputs and capture chips, etc., unfortunately not. The EEPROM which would allow the host system to identify the capture card type and use the correct driver is often not present.

If the card type has been recognized by the kernel device drivers can be checked by looking at the log messages with the help of "dmesg".
In the following example we can see that although 4 video devices have been created because of the known BT878 chips, my capture card type is unknown:

:~$ dmesg
[   49.436525] bttv: Bt8xx card found (2).
[   49.436542] bttv 0000:04:0e.0: PCI INT A -> GSI 18 (level, low) -> IRQ 18
[   49.436553] bttv2: Bt878 (rev 17) at 0000:04:0e.0, irq: 18, latency: 64, mmio: 0xfdffa000
[   49.436574] bttv2: using:  *** UNKNOWN/GENERIC ***  [card=0,autodetected]
[   49.436576] IRQ 18/bttv2: IRQF_DISABLED is not guaranteed on shared IRQs
[   49.436600] bttv2: gpio: en=00000000, out=00000000 in=00ffffff [init]
[   55.868510] tveeprom 3-0050: Huh, no eeprom present (err=-6)?
[   55.868513] bttv2: tuner type unset
[   55.868612] bttv2: registered device video2
[   55.868656] bttv2: registered device vbi2
[

This must be corrected by telling Ubuntu (the video4linux driver) which card type this is, to chose the correct driver version. The problem, especially with cheap cloned cards, is, we often don't know ourselves  the card type or compatible card type.
The only way then is to try...

We can define the card type by putting a config file into the /etc/modprobe.d directory. This can look like this:

alias char-major-81 bttv
options bttv gbuffers=16 card=133,132,133,133 tuner=4,4,4,4

To find the right parameters for a specific card requires usually a bit of research on the internet.
Some useful info about supported cards can be found on the v4l site:
http://linuxtv.org/hg/v4l-dvb/file/tip/linux/Documentation/video4linux/CARDLIST.bttv

The short 2-liner can get any name and must be dropped into the /etc/modprobe.d directory:

~$ ls -l /etc/modprobe.d/
total 36
-rw-r--r-- 1 root root 2386 2010-01-29 07:01 alsa-base.conf
-rw-r--r-- 1 root root  325 2010-04-14 11:26 blacklist-ath_pci.conf
-rw-r--r-- 1 root root 1603 2010-04-14 11:26 blacklist.conf
-rw-r--r-- 1 root root  213 2010-04-14 11:26 blacklist-firewire.conf
-rw-r--r-- 1 root root  660 2010-04-14 11:26 blacklist-framebuffer.conf
-rw-r--r-- 1 root root  156 2010-01-29 07:01 blacklist-modem.conf
lrwxrwxrwx 1 root root   41 2010-10-08 20:50 blacklist-oss.conf -> /lib/linux-sound-base/noOSS.modprobe.conf
-rw-r--r-- 1 root root 1077 2010-04-14 11:26 blacklist-watchdog.conf
-rw-r--r-- 1 root root   85 2010-10-10 15:40 bttv.conf      <====== new file with the 2 lines as shown above
-rw-r--r-- 1 root root   16 2010-01-06 15:12 libpisock9.conf

After this I recommend a system restart. I believe its possible to unload and reload the kernel module, but I am not sure how safe this is.

Now dmesg looks like this (grep filters the interesting lines):

~$ dmesg | grep bttv
[   10.877368] bttv: driver version 0.9.18 loaded
[   10.877371] bttv: using 16 buffers with 2080k (520 pages) each for capture
[   10.877482] bttv: Bt8xx card found (0).
[   10.877498] bttv 0000:04:0c.0: PCI INT A -> GSI 16 (level, low) -> IRQ 16
[   10.877508] bttv0: Bt878 (rev 17) at 0000:04:0c.0, irq: 16, latency: 64, mmio: 0xfdffe000
[   10.877521] bttv0: using: Kodicom 4400R (slave) [card=133,insmod option]
[   10.877523] IRQ 16/bttv0: IRQF_DISABLED is not guaranteed on shared IRQs
[   10.877547] bttv0: gpio: en=00000000, out=00000000 in=00ffffff [init]
[   10.877602] bttv0: tuner absent
[   10.877661] bttv0: registered device video0
[   10.877701] bttv0: registered device vbi0
[   10.877720] bttv0: PLL: 28636363 => 35468950 .
[   10.911063] bttv: Bt8xx card found (1).
[   10.911079] bttv 0000:04:0d.0: PCI INT A -> GSI 17 (level, low) -> IRQ 17
[   10.911090] bttv1: Bt878 (rev 17) at 0000:04:0d.0, irq: 17, latency: 64, mmio: 0xfdffc000
[   10.911107] bttv1: using: Kodicom 4400R (master) [card=132,insmod option]
[   10.911110] IRQ 17/bttv1: IRQF_DISABLED is not guaranteed on shared IRQs
[   10.911143] bttv1: gpio: en=00000000, out=00000000 in=00ffffff [init]
[   10.911239] bttv1: tuner absent
[   10.911324] bttv1: registered device video1
[   10.911385] bttv1: registered device vbi1
[   10.911406] bttv1: PLL: 28636363 => 35468950 .
[   43.100022] bttv: Bt8xx card found (2).
[   43.100039] bttv 0000:04:0e.0: PCI INT A -> GSI 18 (level, low) -> IRQ 18
[   43.100049] bttv2: Bt878 (rev 17) at 0000:04:0e.0, irq: 18, latency: 64, mmio: 0xfdffa000
[   43.100072] bttv2: using: Kodicom 4400R (slave) [card=133,insmod option]
[   43.100074] IRQ 18/bttv2: IRQF_DISABLED is not guaranteed on shared IRQs
[   43.100098] bttv2: gpio: en=00000000, out=00000000 in=00ffffff [init]
[   43.100216] bttv2: tuner absent
[   43.100302] bttv2: registered device video2
[   43.100366] bttv2: registered device vbi2
[   43.100391] bttv2: PLL: 28636363 => 35468950 .. ok
[   75.292023] bttv: Bt8xx card found (3).
[   75.292040] bttv 0000:04:0f.0: PCI INT A -> GSI 19 (level, low) -> IRQ 19
[   75.292050] bttv3: Bt878 (rev 17) at 0000:04:0f.0, irq: 19, latency: 64, mmio: 0xfdff8000
[   75.292073] bttv3: using: Kodicom 4400R (slave) [card=133,insmod option]
[   75.292075] IRQ 19/bttv3: IRQF_DISABLED is not guaranteed on shared IRQs
[   75.292100] bttv3: gpio: en=00000000, out=00000000 in=00ffffff [init]
[   75.292224] bttv3: tuner absent
[   75.292312] bttv3: registered device video3
[   75.292374] bttv3: registered device vbi3
[   75.292400] bttv3: PLL: 28636363 => 35468950 .. ok

No more "unknown" messages, "unset tuner types", etc.
This is no guarantee that the card works, the type could still be wrong!

Next step is to check if we can capture some pictures from the video inputs. A simple piece of SW like xawtv can be used to test this. xawtv can be installed with the synaptic package manager.
Starting xawtv from the Applications/Sound & Video produced a video straight away! Right click on the window lets us select one the 16 video inputs under "video source". I don't know which of the 4 video devices xawtv selects. It seems to be not configurable. Anyway, this test proofs that video4linux can use the card and applications are able to select one of the available 16 video inputs.

Only if the video capture card works, it makes sense to continue the ZM installation.

3) Zoneminder Installation

Zoneminder can be installed using the synaptic package manager. All dependencies will be resolved, Apache and MySQL installed as well. During the installation process, the MySQL root password has to be defined.

A couple of more things need t be tweaked before ZM works:

Script access to video devices:
Only the user "root" and the the group "video" have read and write access to the video devices, as we have seen on the printout above.
The ZM scripts are run under the apache user "www-data". We need to add the user www-data to the group "video" to grant ZM access to the video devices:

~$ sudo usermod -a -G video www-data

Shared memory:
The ZM scripts use shared memory to transfer video images.
There are a couple of partly controversy discussions on how much shared memory is needed and how parameters should be changed.The standard available shared memory seems to be too small.
There is:
shmall - total amount of shared memory for all processes, in pages, default 2097152 pages (=8GB)
shmmax - maximum amount of shared memory allocatable in a single request (single process?), in bytes, default 32MB
(see cat /proc/sys/kernel/shmall  and cat /proc/sys/kernel/shmmax)

A look at what is really used when ZM is running gives ipcs:

~$ sudo ipcs

------ Shared Memory Segments --------
key        shmid      owner      perms      bytes      nattch     status      
0x7a6d0001 1048596    www-data   700        26209192   1                       
0x7a6d0002 1081365    www-data   700        26209192   1                       
0x7a6d0003 1114134    www-data   700        26209192   1                       

Here are 3 cameras running in RGB24 mode, with 520 width and 420 height resolution and an image buffer size of 40 (default). Each of the cameras consumes about 26 MB shared memory!
Increasing the image buffer size under the camera's "Buffer" settings increases the need for shared memory further.

My conclusion: the SHMMAX is a bit tight with 32MB, although it might be sufficient for many cases.

To avoid hitting the limit, I set SHMMAX to 256M as recommended somewhere. This is plenty and should not affect system stability on 2-3 camera system with 2GB of RAM. With bigger systems or with less RAM it could be a good idea to be not too generous with shared memory.

To change SHMMAX permanently, the line

kernel.shmmax = 256000000

needs to be added to /etc/sysctl.conf.
Load the new value with

~$ sudo sysctl -p

or do a system restart.

Linking Apache to the Zoneminder Script

Finally the a link needs to be established to call the ZM script over Apache:

sudo ln -s /etc/zm/apache.conf /etc/apache2/sites-enabled/001-zoneminder

This makes zoneminder available under http://[server]/zm.

Zoneminder is now ready for usage. Cameras and alarm zones need to be defined.

4) Add Cameras

.... to be continued.

6) Letting the server listen on another port

Add

NameVirtualHost *:81
Listen 81

to /etc/apache2/ports.conf

Create a new virtual host config in /etc/apache2/sites-available.
E.g.
- copy the existing "default" to "default-81"
- modify the port of the virtual host as needed: <VirtualHost *:81>
- change the document root to be the zm script location: DocumentRoot /usr/share/zoneminder

Enable the new virtual host by setting a link from the /etc/apache2/sites-enabled directory to the just created file:
sudo ln -s ../sites-available/default-81 002-default-81

Reload apache:
sudo /etc/init.d/apache2 reload

Now ZM is available under http://[server]:81