Install Guide for LogZilla v2.10.0
From Network Management Wiki
Contents |
About
This page will help guide you through a standard installation process.
For this demo, I will be using the v2.10.0 located at The Google code site
Name Change
You may have noticed that I've started using the name LogZilla.
Moving forward, the php-syslog-ng application will be changing it's name to LogZilla in order to facilitate future plans of moving to an Ajax front-end.
Obtaining LogZilla
Sudo to root and then change directories to your web root(we'll want to do most of this as root, so su first):
sudo su - cd /var/www
Download: Grab the latest package from The Google code site and use wget to download it to your local system:
wget http://php-syslog-ng.googlecode.com/files/logzilla_v2.10.0BETA.tgz <- Replace with the current version
Extract:
tar xzvf logzilla_v2.10.0BETA.tgz
Rename the php-syslog-ng directory to logzilla (see #Name_Change)
mv php-syslog-ng logzilla
Requirements
Please note that you should have a decent understanding of Linux, Apache, Mysql and PHP before attempting to use this software. I've made every attempt to make it as easy as possible, but due to the nature of this stuff, it does require a decent skill base to implement and operate properly.
The following tools/software must be installed in order to use LogZilla:
- syslog-ng
- Apache
- PHP
- MySQL v5.1 or better
- libmysqlclient-dev (needed for compiling Sphinx)
- php-gd (for graphs)
- php-cli for (for command line scripts)
- php5-mysql
- msttcorefonts (for graph fonts)
- build-essential (you'll need this later for building perl modules and other system stuff)
- Sphinx
In Ubuntu, you can install everything except Sphinx by typing:
sudo aptitude install apache2 php5 php5-gd php5-cli php5-mysql mysql-server-5.1 msttcorefonts build-essential libmysqlclient-dev
From the command line to install everything at once.
(Yes, it's that easy - see why I like Ubuntu?)
Syslog-ng
This logging system is based on data collected from a program called Syslog-NG which is "is an open source implementation of the Syslog protocol for UNIX and UNIX-like systems. It extends the original syslogd model with content-based filtering, rich filtering capabilities, flexible configuration options and adds important features to syslog, like using TCP for transport."
In the case of LogZilla, we're going to use it to collect syslog messages from our network and store the information into a MySQL database for reporting capabilities.
Here's a simple diagram of how these pieces fit together:
Installing syslog-ng
This section covers syslog-ng using Ubuntu, if you use a different distro you're on your own...
From a console, type:
sudo aptitude install syslog-ng
You will likely see an error in ubuntu like this:
Remove the following packages: ubuntu-minimal
It's a bug in Ubuntu and it's safe to continue.
Apache
Naturally, if we're going to use a web interface, we'll need a web server :-)
First, edit the /etc/apache2/apache2.conf file and add a ServerName directive
sudo vi /etc/apache2/apache2.conf
When you're done, it should look like this (replace logzilla with your server's name):
ServerRoot "/etc/apache2" <<- Existing line ServerName logzilla
Replace 'logzilla' with your actual server name
Note: You can skip the following section if you are installing to the root web server.
Not all systems will need to use the following config. This is only provided as an example.
Next, create a file in /etc/apache2/sites-available called "logzilla" and add the following to it:
# LogZilla
Alias /logs "/var/www/logzilla/html/"
<Directory "/var/www/logzilla/html/">
Options Indexes MultiViews FollowSymLinks
AllowOverride All
Order allow,deny
Allow from all
</Directory>
Note: AllowOverride should be set to "All" so we can modify php variables using a .htaccess file (more on that later)
Now save this file in the appropriate location. For Ubuntu users, it would be saved as:
/etc/apache2/sites-available/logzilla
Then, for Ubuntu, you would type:
a2ensite logzilla
If you are on a distro other than Ubuntu, you'll have to look up the documentation to see how to implement this (you might be able to simply add it to the default config file)
Now restart Apache and make sure you don't see any errors.
sudo /etc/init.d/apache2 restart * Restarting web server apache2 [ OK ]
Finally, go browse to http://<ipaddress>/<directory> and see if it's working...
MySQL
LogZilla v2.10.0 and up will only work with MySQL v5.1 or greater. If you don't have MySQL 5.1, then stop now and either upgrade it, or use LogZilla v2.9.9
The install guide for LogZilla v2.9.9 can be found here: LogZilla Installation Guide
You shouldn't have to do anything from the command line for installing MySQL other than what we did in the prerequisites section.
All table modifications will be made for you during the LogZilla install.
PHP
This section covers PHP using Ubuntu, if you use a different distro you're on your own...
LogZilla is designed to work with PHPv5.x
If you are using PHP v4, and plan to use the CEMDB (Cisco Error Message Database), then you will need to convert the CEMDB.class file to an older format as noted in the issues list on the code site:
http://code.google.com/p/php-syslog-ng/issues/detail?id=13&can=1&q=cemdb
If you don't, you will get errors like this:
Parse error: syntax error, unexpected T_STRING, expecting T_OLD_FUNCTION or T_FUNCTION or T_VAR or '}' in /var/www/php-syslog-ng/includes/CEMDB.class.php on line 11
After you've installed everything as noted in the prerequisites section above, edit the /etc/php5/apache2/php.ini file and change a few settings that we'll need during the web portion:
sudo vi /etc/php5/apache2/php.ini
Change:
memory_limit = 16M
to:
memory_limit = 128M
Change:
max_execution_time = 30
to:
max_execution_time = 300
You should also do the same for /etc/php5/cli/php.ini
Don't forget to restart apache to start using PHP
sudo /etc/init.d/apache2 restart * Restarting web server apache2 [ OK ]
PERL
Perl is used for the installation of LogZilla as well as the database inserts during normal operation - these files are located in the scripts/ directory.
The following perl modules are used with LogZilla and will need to be installed prior to running the install script:
Date::Calc Text::LevenshteinXS
You can easily install them from the command line by typing:
cpan Date::Calc Text::LevenshteinXS
Permissions
Make sure you set the html/ directory to the apache web owner.
For example, in Ubuntu you would do:
chown -R www-data:www-data /var/www/logzilla/html
Install LogZilla
NOTE: Before starting this process, be sure you've completed the items listed above!
The web-based install has been removed as of LogZilla v2.10 and has been replaced by a perl script.
This method is a lot easier for me to maintain than a web interface and provides better automation for things like setting up the database, syslog-ng, cron, logrotate and updating the paths in script files.
To start the install, go to your scripts directory and run install.pl
cd /var/www/logzilla/scripts ./install.pl
Sphinx
As of LogZilla v2.10, I've incorporated Sphinx. Here's a description of Sphinx from their website:
Sphinx is a full-text search engine, distributed under GPL version 2. Commercial license is also available for embedded use. Generally, it's a standalone search engine, meant to provide fast, size-efficient and relevant fulltext search functions to other applications. Sphinx was specially designed to integrate well with SQL databases and scripting languages. Currently built-in data sources support fetching data either via direct connection to MySQL or PostgreSQL, or using XML pipe mechanism (a pipe to indexer in special XML-based format which Sphinx recognizes). As for the name, Sphinx is an acronym which is officially decoded as SQL Phrase Index. Yes, I know about CMU's Sphinx project.
For this install, I will be using Sphinx v0.9.8.1 which can be downloaded from the Sphinx Download Page
Sphinx allows me to offer much better scalability for larger LogZilla installations. In my tests, I went from querying 100m rows in 30 seconds to querying using Sphinx in 0.8 seconds.
To install sphinx:
cd /var/www <- or wherever you plan to install sphinx, such as /var/www/sphinx wget http://www.sphinxsearch.com/downloads/sphinx-0.9.8.1.tar.gz tar xzvf sphinx-0.9.8.1.tar.gz mv sphinx-0.9.8.1 sphinx cd sphinx ./configure && make && make install
If you get an error like the one below, then you haven't completed the #Requirements
****************************************************************************** ERROR: cannot find MySQL include files. Check that you do have MySQL include files installed. The package name is typically 'mysql-devel'. If include files are installed on your system, but you are still getting this message, you should do one of the following: 1) either specify includes location explicitly, using --with-mysql-includes; 2) or specify MySQL installation root location explicitly, using --with-mysql; 3) or make sure that the path to 'mysql_config' program is listed in your PATH environment variable. To disable MySQL support, use --without-mysql option. ******************************************************************************
After Sphinx is done installing, run the following command:
/var/www/logzilla/scripts/spindex.sh full
This will create the initial index for your tables
Next, start the sphinx daemon by typing:
/usr/local/bin/searchd -c /var/www/logzilla/sphinx/sphinx.conf
That's it for getting it installed, the entries in /etc/cron.d/logzilla will take care of indexing for you.
Misc Requirements
Logrotate
A copy of the LogZilla logrotate settings will be install in /etc/logrotate.d for you during the install.
Cron
A copy of the LogZilla cron settings will be installed in /etc/cron.d for you during the install.
Advanced Features
This section covers advanced options for implementation
Authentication Methods
Some alternate authentication methods are available which include:
LDAP
After LogZilla is installed and running properly, you can browse to the admin interface and change the following settings in order to enable LDAP:
AUTHTYPE - Set to LDAP LDAP_BASE_DN - This variable sets the LDAP Base DN if LDAP is enabled LDAP_CN - This variable is used to set the LDAP CN LDAP_DOMAIN - LDAP Domain name LDAP_MS - This variable is used to enable MS-type LDAP autentication when LDAP is enabled LDAP_PRIV - This variable is NOT used by LogZilla yet. LDAP_RO_FILTERS - This variable is NOT used by LogZilla yet. LDAP_RO_GRP - This variable is NOT used by LogZilla yet. LDAP_RW_GRP - This variable is NOT used by LogZilla yet. LDAP_SRV - This variable sets the LDAP server name to use if LDAP is enabled
Web Basic Auth (htaccess)
After LogZilla is installed and running properly, you can browse to the admin interface and change the following settings in order to enable htaccess support using mod_auth_krb5:
AUTHTYPE - Set to webbasic
Note that you will still need to add the appropriate user to the MySQL database before this will work.
For assistance with setting up apache .htaccess, please visit http://home.golden.net/htaccess.html
For more information on this feature, please visit http://code.google.com/p/php-syslog-ng/issues/detail?id=62
Message Deduplication
LogZilla features an automatic message deduplication function which can be enabled in the admin interface by setting:
DEDUP - This variable is used to Enable or Disable Message Deduplication in the db_insert.pl script. DEDUP_DIST - This variable is used to set distance for message deduplication. DEDUP_WINDOW - If Message deduplication is enabled, this setting is used to indicate the amount of time (in seconds) to compare messages from the same host.
It works great, but has some caveats that you should be aware of prior to using it.
Deduplication uses an algorithm similar to Levenshtein's and is used to compare the number of "edits" it would take to make each of the compared strings become the same.
The result is displayed as a "distance" (a variable you can alter by setting the DEDUP_DIST in the admin interface)
This allows LogZilla to compare incoming messages to those stored in the database.
When a message arrives, deduplication will check the incoming message and compare it to messages in the database that are from the same:
- host
- facility
- priority
- level
- tag
- within the last X minutes (this window is configurable by setting DEDUP_WINDOW in the admin interface)
If rows in the database are found to match the incoming message, the deduplication function function will update the original row with a new "First Occurrence", "Last Occurrence" and "Count" to reflect the duplicate message and will discard the incoming message and any other duplicates in the database it finds (within the specified time range).
Caveats
- If your company has to comply to PCI standards, then deduplication is not for you (you may, however, consider
splitting up messages to two separate servers, one for analyzing and reporting, and one for storing ALL messages for PCI compliance)
- If you are getting a lot of messages per day (multi-millions), deduplication may actually be too slow for you to use since it has to do table lookups for each incoming message.
I would encourage you to at least test it though as it does provide some major advantages.
Advantages
Enabling the message deduplication feature allows you to save important DB storage space to allow for much faster analyzing and reporting.
For example, a recent analysis of a customer of mine had the following in 5 days worth of logs:
- There were 675 Hosts with a total of 675,109 messages.
- Of the 675,109 messages, 99.84% were duplicates
- Their Top 10 reporting devices had more than 25,000 single messages repeated – the top device had almost 60,000.
This means that if they were deduplicating events before they got stored into the Syslog server’s database, then only 2,846 rows would be used in that database instead of 675,109 individual rows.
The benefits here should be obvious...searching across 3,000 rows is a lot faster then searching through 700,000...
Before implementing this feature, please be aware of the potential damage you can do (i.e. deleted rows).
I encourage you to read more about it here
Logreplay
I've included a new in script as of version 2.9.9 that will allow you to "replay" a log file taken from another server. The script is located in:
- scripts/contrib/logreplay/logreplay.pl
To use the sample logs included simply un-gzip it:
gzip -d syslog.sample.gz
And run the logreplay script:
./logreplay.pl -h
Which will give you help on the script:
This program is used to replay a standard *Cisco* syslog dumpfile into the local syslog receiver (syslog-ng)
usage: ./logreplay.pl [-hvfs]
-h : this (help) message
-v : verbose output
-f : Filename to import (required)
-s : path to the spoof program (required)
example: ./logreplay.pl -v -f ./syslog.sample -s ./spoof
So, to run it, you would do:
./logreplay.pl -v -f ./syslog.sample -s ./spoof
The "spoof" program that I've included will rewrite the outgoing syslog packet and insert the hostnames from the syslog.sample file so that when syslog-ng receives the messages they appear to come from that host instead of your local machine.
In order to use spoof, you will need to compile it like so:
gcc spoof_syslog.c -o spoof_syslog
This will create the ./spoof_syslog executable used by logreplay.pl
Upgrade Procedures
I typically don't provide an upgrade procedure with new versions of LogZilla.
The main reason for this is simply because I barely have enough time these days to work on the code itself.
If someone would like to join the development team and contribute this, then please do :-)
If you need to save your old log data, the easiest thing to do is to just install the new version to a separate URL and Database and leave the old one running in parallel until you no longer require the data in it.
Appendix/FAQ
If you ever need to reset the admin password, you can do it from a mysql shell:
update users set pwhash=md5('MYNEWPASSWORD') where username='admin';
