diff --git a/docs/installationguide/ubuntu.rst b/docs/installationguide/ubuntu.rst index b95d46a89..fa065cb96 100644 --- a/docs/installationguide/ubuntu.rst +++ b/docs/installationguide/ubuntu.rst @@ -1,64 +1,466 @@ Ubuntu ====== -Option A: Install a ready made package ---------------------------------------- +.. contents:: -Installation procedure (common for all versions of Ubuntu) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Easy Way: Install ZoneMinder from a package (Ubuntu 15.x+) +----------------------------------------------------------- +These instructions are for a brand new ubuntu 15.04 system which does not have ZM installed. -It is important that you first apply any system software upgrades first to Ubuntu, especially if you have just created a new image of Ubuntu. -Not doing this may cause the PPA process to fail and complain about various unmet dependencies. - -If you also plan to install the database in the same server (which is typically the case), first do: +**Step 1**: Make sure we add the correct packages :: - sudo apt-get install mysql-server + sudo add-apt-repository ppa:iconnor/zoneminder-master + sudo apt-get update -This will ask you for a user and password to configure for Zoneminder. -Note that when you install the PPA, it will also create a username of zmuser and a password of zmpass irrespective of what you select at this stage - -Now add the ppa repository path: +if you don't have mysql already installed: :: - sudo apt-add-repository ppa:iconnor/zoneminder + sudo apt-get install mysql-server + +This will ask you to set up a master password for the DB (you are asked for the mysql root password when installing mysql server). + +**Step 2**: Install ZoneMinder -Once you have updated the repository then update and install the package.: - :: - sudo apt-get update - sudo apt-get install zoneminder + sudo apt-get install zoneminder +**Step 3**: Configure the Database +:: + sudo mysql -uroot -p < /usr/share/zoneminder/db/zm_create.sql + mysql -uroot -p -e "grant select,insert,update,delete,create,alter,index,lock tables on zm.* to 'zmuser'@localhost identified by 'zmpass';" -Post Install steps for Ubuntu 15.x or newer (systemd) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +You don't really need this, but no harm (needed if you are upgrading) :: sudo /usr/bin/zmupdate.pl + +**Step 4**: Configure systemd to recognize ZoneMinder and configure Apache correctly: + +:: + sudo systemctl enable zoneminder sudo a2enconf zoneminder + sudo a2enmod cgi + sudo chown -R www-data:www-data /usr/share/zoneminder/ + + +We need this for API routing to work: + +:: + + sudo a2enmod rewrite + +This is probably a bug with iconnor's PPA as of Oct 3, 2015 with package 1.28.107. After installing, ``zm.conf`` does not have the right read permissions, so we need to fix that. This may go away in future PPA releases: + +:: + + sudo chown www-data:www-data /etc/zm/zm.conf + +We also need to install php5-gd (as of 1.28.107, this is not installed) + +:: + + sudo apt-get install php5-gd + +**Step 5**: Edit Timezone in PHP + +:: + + vi /etc/php5/apache2/php.ini + +Look for [Date] and inside it you will see a date.timezone +that is commented. remove the comment and specific your timezone. +Please make sure the timezone is valid (see this: http://php.net/manual/en/timezones.php) + +In my case: + +:: + + date.timezone = America/New_York + +**Step 6**: Restart services + +:: + sudo service apache2 reload - systemctl restart zoneminder + sudo systemctl restart zoneminder -You should now be able to view the zoneminder interface at ``http://localhost/zm`` (replace localhost with your server IP if you are accessing it remotely) -.. image:: images/zm_first_screen_post_install.png +**Step 7: make sure live streaming works**: Make sure you can view Monitor streams: + +startup ZM console in your browser, go to ``Options->Path`` and make sure ``PATH_ZMS`` is set to ``/zm/cgi-bin/nph-zms`` and restart ZM (you should not need to do this for packages, as this should automatically work) + + +**Step 8**: If you have changed your DB login/password from zmuser/zmpass, the API won't know about it + +If you changed the DB password **after** installing ZM, the APIs will not be able to connect to the DB. + +If you have, go to ``zoneminder/www/api/app/Config`` & Edit ``database.php`` + +There is a class there called ``DATABASE_CONFIG`` - change the ``$default`` array to reflect your new details. Example: + +:: + + public $default = array( + 'datasource' => 'Database/Mysql', + 'persistent' => false, + 'host' => 'localhost', + 'login' => 'mynewDBusername', + 'password' => 'mynewDBpassword' + 'database' => 'zm', + 'prefix' => '', + //'encoding' => 'utf8', + ); + + +You are done. Lets proceed to make sure everything works: + +Making sure ZM and APIs work: + +1. open up a browser and go to ``http://localhost/zm`` - should bring up ZM +2. (OPTIONAL - just for peace of mind) open up a tab and go to ``http://localhost/zm/api`` - should bring up a screen showing CakePHP version with some green color boxes. Green is good. If you see red, or you don't see green, there may be a problem (should not happen). Ignore any warnings in yellow saying "DebugKit" not installed. You don't need it +3. open up a tab in the same browser and go to ``http://localhost/zm/api/host/getVersion.json`` + +If it responds with something like: + +:: + + { + "version": "1.28.107", + "apiversion": "1.28.107.1" + } + + +**Then your APIs are working** + +Make sure ZM and APIs work with security: +1. Enable OPT_AUTH in ZM +2. Log out of ZM in browser +3. Open a NEW tab in the SAME BROWSER (important) and go to ``http://localhost/zm/api/host/getVersion.json`` - should give you "Unauthorized" along with a lot more of text +4. Go to another tab in the SAME BROWSER (important) and log into ZM +5. Repeat step 3 and it should give you the ZM and API version + +**Congrats** your installation is complete + + +Easy Way: Install ZoneMinder from a package (Ubuntu 14.x) +----------------------------------------------------------- +**These instructions are for a brand new ubuntu 14.x system which does not have ZM installed.** + +**Step 1:** Install ZoneMinder + +:: + + sudo add-apt-repository ppa:iconnor/zoneminder-master + sudo apt-get update + sudo apt-get install zoneminder + +(just press OK for the prompts you get) + +**Step 2:** Set up DB + +:: + + sudo mysql -uroot -p < /usr/share/zoneminder/db/zm_create.sql + mysql -uroot -p -e "grant select,insert,update,delete,create,alter,index,lock tables on zm.* to 'zmuser'@localhost identified by 'zmpass';" + +**Step 3:** Set up Apache + +:: + + sudo a2enconf zoneminder + sudo a2enmod rewrite + sudo a2enmod cgi + +**Step 4:**:Some tweaks that will be needed: + +Edit /etc/init.d/zoneminder: + +add a ``sleep 10`` right after line 25 that reads ``echo -n "Starting $prog:"`` +(The reason we need this sleep is to make sure ZM starts after mysqld starts) + +As of Oct 3 2015, zm.conf is not readable by ZM. This is likely a bug and will go away in the next package + +:: + + sudo chown www-data:www-data /etc/zm/zm.conf + + + +**Step 5**: If you have changed your DB login/password + +If you changed the DB password **after** installing ZM, the APIs will not be able to connect to the DB. + +If you have, go to zoneminder/www/api/app/Config & Edit ``database.php`` + +There is a class there called ``DATABASE_CONFIG`` - change the ``$default`` array to reflect your new details. Example: + +:: + + public $default = array( + 'datasource' => 'Database/Mysql', + 'persistent' => false, + 'host' => 'localhost', + 'login' => 'mynewDBusername', + 'password' => 'mynewDBpassword' + 'database' => 'zm', + 'prefix' => '', + //'encoding' => 'utf8',` + ); + +We also need to install php5-gd (as of 1.28.107, this is not installed) + +:: + + sudo apt-get install php5-gd + + +**Step 6**: Edit Timezone in PHP + +vi /etc/php5/apache2/php.ini +Look for [Date] and inside it you will see a date.timezone +that is commented. remove the comment and specific your timezone. +Please make sure the timezone is valid (see [this](http://php.net/manual/en/timezones.php)) + +In my case: + +:: + + date.timezone = America/New_York + + +**Step 7: make sure live streaming works**: Make sure you can view Monitor streams: + +startup ZM console in your browser, go to ``Options->Path`` and make sure ``PATH_ZMS`` is set to ``/zm/cgi-bin/nph-zms`` and restart ZM (you should not need to do this for packages, as this should automatically work) + + + +restart: + +:: + + sudo service apache2 restart + /etc/init.d/zoneminder restart + +**Step 8**: Making sure ZM and APIs work: (optional - only if you need APIs) + +1. open up a browser and go to ``http://localhost/zm`` - should bring up ZM +2. (OPTIONAL - just for peace of mind) open up a tab and go to ``http://localhost/zm/api`` - should bring up a screen showing CakePHP version with some green color boxes. Green is good. If you see red, or you don't see green, there may be a problem (should not happen). Ignore any warnings in yellow saying "DebugKit" not installed. You don't need it +3. open up a tab in the same browser and go to ``http://localhost/zm/api/host/getVersion.json`` + +If it responds with something like: + +:: + + { + "version": "1.28.107", + "apiversion": "1.28.107.1" + } + +Then your APIs are working + +Make sure you can view Monitor View: +1. Open up ZM, configure your monitors and verify you can view Monitor feeds. +2. If not, open up ZM console in your browser, go to ``Options->Path`` and make sure ``PATH_ZMS`` is set to ``/zm/cgi-bin/nph-zms`` and restart ZM (you should not need to do this for packages, as this should automatically work) + +Make sure ZM and APIs work with security: +1. Enable OPT_AUTH in ZM +2. Log out of ZM in browser +3. Open a NEW tab in the SAME BROWSER (important) and go to ``http://localhost/zm/api/host/getVersion.json`` - should give you "Unauthorized" along with a lot more of text +4. Go to another tab in the SAME BROWSER (important) and log into ZM +5. Repeat step 3 and it should give you the ZM and API version + +**Congrats** Your installation is complete -Post install steps for Ubuntu 14.x or older (SystemV) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Harder Way: Build Package From Source +------------------------------------------- +(These instructions assume installation from source on a ubuntu 15.x+ system) + +**Step 1:** First make sure you have the needed tools + +:: + + sudo apt-get update + sudo apt-get install cmake git + +**Step 2:** Next up make sure you have all the dependencies + +:: + + sudo apt-get install apache2 mysql-server php5 php5-mysql build-essential libmysqlclient-dev libssl-dev libbz2-dev libpcre3-dev libdbi-perl libarchive-zip-perl libdate-manip-perl libdevice-serialport-perl libmime-perl libpcre3 libwww-perl libdbd-mysql-perl libsys-mmap-perl yasm automake autoconf libjpeg8-dev libjpeg8 apache2 libapache2-mod-php5 php5-cli libphp-serialization-perl libgnutls-dev libjpeg8-dev libavcodec-dev libavformat-dev libswscale-dev libavutil-dev libv4l-dev libtool ffmpeg libnetpbm10-dev libavdevice-dev libmime-lite-perl dh-autoreconf dpatch policykit-1 libpolkit-gobject-1-dev libextutils-pkgconfig-perl libcurl3 libvlc-dev libcurl4-openssl-dev curl php5-gd + +(you are asked for the mysql root password when installing mysql server - put in a password that you'd like). + +**Step 3:** Download ZoneMinder source code and compile+install: + +:: + + git clone https://github.com/ZoneMinder/ZoneMinder.git + cd ZoneMinder/ + git submodule init + git submodule update + cmake . + make + sudo make install + +**Step 4:** Now make sure your symlinks to events and images are set correctly: + +:: + + sudo ./zmlinkcontent.sh + +**Step 5:** Now lets make sure ZM has DB permissions to write to the DB: + +:: + + mysql -uroot -p -e "grant select,insert,update,delete,create,alter,index,lock tables on zm.* to 'zmuser'@localhost identified by 'zmpass';" + +**Step 6:** Now lets create the DB & its tables that ZM needs + +:: + + mysql -uroot -p + Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch + AllowOverride All + Require all granted + + + Alias /zm /usr/local/share/zoneminder/www + + php_flag register_globals off + Options Indexes FollowSymLinks + + DirectoryIndex index.php + + + + + AllowOverride All + + +**Step 11:** Now lets make sure ZM can read/write to the zoneminder directory: + +:: + + sudo chown -R www-data:www-data /usr/local/share/zoneminder/ + + +**Step 12:** Make sure you can view Monitor View + +1. Open up ZM, configure your monitors and verify you can view Monitor feeds +2. If not, open up ZM console in your browser, go to ``Options->Path`` and make sure ``PATH_ZMS`` is set to ``/zm/cgi-bin/nph-zms`` and restart ZM + +**Step 13**: Edit Timezone in PHP + +vi /etc/php5/apache2/php.ini +Look for [Date] and inside it you will see a date.timezone +that is commented. remove the comment and specific your timezone. +Please make sure the timezone is valid (see http://php.net/manual/en/timezones.php) + +In my case: + +:: + + date.timezone = America/New_York + +**Step 14:** Finally, lets make a config change to apache (needed for htaccess overrides to work for APIs) +Edit /etc/apache2/apache2.conf and add this: + +:: + + + AllowOverride All + Require all granted + + +Restart apache + +:: + + sudo service apache2 reload + +You are done. Lets proceed to make sure everything works: + +Making sure ZM and APIs work: + +1. open up a browser and go to ``http://localhost/zm`` - should bring up ZM +2. (OPTIONAL - just for peace of mind) open up a tab and go to ``http://localhost/zm/api`` - should bring up a screen showing CakePHP version with some green color boxes. Green is good. If you see red, or you don't see green, there may be a problem (should not happen). Ignore any warnings in yellow saying "DebugKit" not installed. You don't need it +3. open up a tab in the same browser and go to ``http://localhost/zm/api/host/getVersion.json`` + +If it responds with something like: + +:: + + { + "version": "1.28.107", + "apiversion": "1.28.107.1" + } + +Then your APIs are working + +Make sure ZM and APIs work with security: +1. Enable OPT_AUTH in ZM +2. Log out of ZM in browser +3. Open a NEW tab in the SAME BROWSER (important) and go to ``http://localhost/zm/api/host/getVersion.json`` - should give you "Unauthorized" along with a lot more of text +4. Go to another tab in the SAME BROWSER (important) and log into ZM +5. Repeat step 3 and it should give you the ZM and API version + +**Congrats** your installation is complete + Suggested changes to MySQL (Optional but recommended) -""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +------------------------------------------------------ For most of you Zoneminder will run just fine with the default MySQL settings. There are a couple of settings that may, in time, provide beneficial especially if you have a number of cameras and many events with a lot of files. One setting we recommend is the "innodb_file_per_table" This will be a default setting in MySQL 5.6 but should be added in MySQL 5.5 which comes with Ubuntu 14.04. A description can be found here: http://dev.mysql.com/doc/refman/5.5/en/innodb-multiple-tablespaces.html To add "innodb_file_per_table" edit the my.cnf file: @@ -72,90 +474,4 @@ Save and exit. Restart MySQL ``service mysql restart`` -Adding a sleep for mysql dependency (Ubuntu 14.x and below only) -"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" -We recommend you add a "sleep" command just after ``start() {`` in ``/etc/init.d/zoneminder`` to make sure mysql starts before ZoneMinder does. To do this, -simply modify ``/etc/init.d/zoneminder`` at around line 25 (where you will find the start function) to look like this: - -:: - - start() { - echo -n "Making sure mysql started... Sleeping for 10 seconds..." - sleep 10 - echo -n "Starting $prog: " - -Making Apache aware of ZoneMinder -"""""""""""""""""""""""""""""""""""""""""""" - -Next, we need to make sure apache knows about zoneminder's configuration for apache. - -:: - - ln -s /etc/zm/apache.conf /etc/apache2/conf-available/zoneminder.conf - -If you are upgrading from an old version: - -:: - - sudo /usr/bin/zmupdate.pl - -Then look for ``/etc/apache2/conf-enable/zm.conf`` - if you have it, please remove it - -:: - - a2enconf zoneminder - adduser www-data video - - -lets make sure we restart apache: - -:: - - service apache2 restart - - -You should now be able to view the zoneminder interface at ``http://localhost/zm`` (replace localhost with your server IP if you are accessing it remotely) - -.. image:: images/zm_first_screen_post_install.png - - -Finally, in the zoneminder web interface, go to Options->Paths, change PATH_ZMS to ``/zm/cgi-bin/nph-zms`` - - -Option B: Build Package From Source -------------------------------------------- - -A fresh build based on master branch running Ubuntu 1204 LTS. Will likely work for other versions as well.:: - - root@host:~# aptitude install -y apache2 mysql-server php5 php5-mysql build-essential libmysqlclient-dev libssl-dev libbz2-dev libpcre3-dev libdbi-perl libarchive-zip-perl libdate-manip-perl libdevice-serialport-perl libmime-perl libpcre3 libwww-perl libdbd-mysql-perl libsys-mmap-perl yasm automake autoconf libjpeg8-dev libjpeg8 apache2-mpm-prefork libapache2-mod-php5 php5-cli libphp-serialization-perl libgnutls-dev libjpeg8-dev libavcodec-dev libavformat-dev libswscale-dev libavutil-dev libv4l-dev libtool ffmpeg libnetpbm10-dev libavdevice-dev libmime-lite-perl dh-autoreconf dpatch; - - root@host:~# git clone https://github.com/ZoneMinder/ZoneMinder.git zoneminder; - root@host:~# cd zoneminder; - root@host:~# ln -s distros/ubuntu1204 debian; - root@host:~# dpkg-checkbuilddeps; - root@host:~# dpkg-buildpackage; - - -One level above you'll now find a deb package matching the architecture of the build host\::: - - root@host:~# ls -1 ~/zoneminder\*; - /root/zoneminder_1.26.4-1_amd64.changes - /root/zoneminder_1.26.4-1_amd64.deb - /root/zoneminder_1.26.4-1.dsc - /root/zoneminder_1.26.4-1.tar.gz - - -The dpkg command itself does not resolve dependencies. That's what high-level interfaces like aptitude and apt-get are normally for. Unfortunately, unlike RPM, there's no easy way to install a separate deb package not contained with any repository. - -To overcome this "limitation" we'll use dpkg only to install the zoneminder package and apt-get to fetch all needed dependencies afterwards. Running dpkg-reconfigure in the end will ensure that the setup scripts e.g. for database provisioning were executed.:: - - root@host:~# dpkg -i /root/zoneminder_1.26.4-1_amd64.deb; apt-get install -f; - root@host:~# dpkg-reconfigure zoneminder; - -Alternatively you may also use gdebi to automatically resolve dependencies during installation\::: - - root@host:~# aptitude install -y gdebi; - root@host:~# gdebi /root/zoneminder_1.26.4-1_amd64.deb; - - sudo apt-get install apache2 mysql-server php5 php5-mysql build-essential libmysqlclient-dev libssl-dev libbz2-dev libpcre3-dev libdbi-perl libarchive-zip-perl libdate-manip-perl libdevice-serialport-perl libmime-perl libpcre3 libwww-perl libdbd-mysql-perl libsys-mmap-perl yasm automake autoconf libjpeg-turbo8-dev libjpeg-turbo8 apache2-mpm-prefork libapache2-mod-php5 php5-cli