Limph
From JComServ Documentation
Limph Is Monitoring Pingable Hosts
Limph is designed as a Nagios and Node Runner replacement. The impetus behind the creation of this application was the difficulty for the Unix novitiate in configuring Nagios (specifically, the lack of a means to configure hosts over the web), and the incompatibility of Node Runner with PHP5.
Contents |
Installation
Requirements
Limph requires PHP >= 4.3.0 and either MySQL >= 3.23, PostgreSQL (works with 8.1, earlier untested), SQLite (experimental) or SQLite/PDO (fully functional). If using SQLite, be sure that the version and installation you're using supports SQLite, as this is not universally the case.
Email notifications require access to an email server.
Use of the host agents requires the mcrypt and mhash PHP extensions on both client and server. Many Linux distributions include packages for easy installations.
Limph has been tested on Linux, but should run on any *nix that supports PHP. The DB can be run remotely or locally.
PHP files
Download the tar.gz and unpack into a folder withing the desired place in your webserver's docroot.
Be sure to change the permissions on poller.php to prevent access by the webserver user(such as apache or nobody) and allow access by the user under which you will be running the poller's cron job (see below).
For any hosts on which you wish to use the host agent, copy the host_agent.php into a secure place on each host, preferably in the home directory of a user created for this purpose. Choose a password string, the longer the better, and place this in the $secret variable line in both the host_agent.php files on the client hosts and the input.php file in the Limph installation.
Set the http address of the Limph installation and $disable=0 on the host_agent.php files on the clients, but NOT on the one in the Limph installation. Configure the disk array line in the client host_agent.php files.
Database setup
Create a database on your DB server, and create a DB user with ALL permissions for your limph database, but none for anything else. Populate the schema and inital data with mysql -uroot -p YOURDB < limph.sql for MySQL and psql -d limph -f limph.pg.sql for PostgreSQL. Be sure to substitute limph_my323.sql if you're running MySQL 3.23.
If making use of the experimental and as yet untested SQLite support, you may sqlite3 /path/to/your/db < limph.sqlite.sql. Make sure this is outside of your webroot, as the webserver user needs to have read and write access to the DB and the directory in which it resides.
Edit config.php to contain the proper host, username, password and dbname for your Limph database (and dbpath for SQLite). Make sure the dbtype variable is set to the type of RDBMS you're using.
Cron job setup
Set up a cron job to run php /path/to/poller.php > /dev/null 2>&1 once per minute as a user other than the webserver user. By using a user other than that of the webserver user, it is impossible for a hostile third party to run the poller from the LAN or public internet, preventing a DOS attack.
An example crontab entry would look like * * * * * php -q /path/to/limph/poller.php > /dev/null 2>&1
Set up cron jobs on each client on which you want to use the host_agent.php. This doesn't need to run as often as the poller, and could be daily, hourly, or any other interval of which cron or your Task Scheduler are capable. A cron entry could like * 1 * * * php -q /home/limphuser/host_agent.php > /dev/null 2>&1
Upgrading
To upgrade an existing Limph installation, complete the following steps in the order listed.
- Back up your database(mysql_dump, pg_dump, or make a copy of your SQLite db file)
- Back up your config.php
- Replace all files in your installation with the files from the new tar.gz
- Double-check poller.php permissions (see above)
- Migrate settings from old config.php to new config.php
- Edit upgrade.php to include proper DB type, DB path(if using SQLite), host, DB name and ROOT DB user/password.
- The poller will detect a version difference between the code and database, and upgrade the database.
Initial setup
Initial Login
Log in with the ID admin, with the password admin.
It would be prudent at this point to click on Change Password and change the admin password to something besides admin. This will help prevent others from altering your Limph installation.
Create Host Groups
Click on Edit Host Groups.
Add at least one group. If adding additional groups, specify the column and priority to lay the groups out. Groups with higher priority get displayed further down the page.
Add hosts
Click on Add Host and enter in the requested information. Both UDP and port-specific TCP checks are available. The UDP check takes the place of the standard ICMP ping check, which is somewhat awkward to properly implement in PHP.
Once submitted, the poller will begin checking the host once per minute, as well as logging history.
As of version 1.7, there is a portscanning tool available. Both UPD and TCP scans may be done, to aid in determining what ports may be monitored on a given host. NOTE: If a TCP range is selected, the host is first subjected to a UDP check which must be passed before the TCP range will be scanned. This is to prevent a nasty hang that can be caused by a long series of TCP check failures. If the host you're scanning doesn't respond to UDP, you can still individually test TCP ports.
Host Discovery
An alternate method for adding hosts is the host discovery tool (version>=1.8). This is accessible to admin level users via the admin menu. Enter a subnet, defined for this purpose as the first 3 dotted octets of a 10., 172., or 192. private network. It will then UDP check each IP, and then perform a 1-1024 TCP scan on any hosts it finds. It will then present a list, and allow you to add any host/port not already being monitored.
Add users
Click on Edit Users, and add any users desired. Notification settings are configured from this screen, as well.
Set up Host Agents
Limph now includes support for remote agents, installed on systems you wish to have more detailed information on. There is currently support for checking the free space on a disk partition, and measuring system load.
First, on your Limph installation, edit input.php and set $secret to a long, complex, secret string. Next, add the host to limph, with a UDP or TCP check. Then, copy host_agent.php to a secret location on the host you wish to monitor. Edit host_agent.php, and change $secret to match the value in input.php. Then set up a cron job to execute php -q /path/to/host_agent.php > /dev/null 2>&1 as often as desired. Once the cron job has run at least once, you should begin to see information being logged in the host's page. Once this has taken place, you may set thresholds for disk and load, so that when the measured values drop below the thresholds, you will be notified (if enabled).
Usage
Main view
The main screen displays the host group. If not set to Collapse, individual hosts are displayed. Host host's name, port(if applicable) and status are displayed. The key at the bottom indicates the status colors.
Tree view
Tree view is helpful in visualizing the Parent/Child relationships between hosts. Due to Limph's dependancy checking poller, if a host is down, any hosts depending on it are not checked, but are marked as invisible. No downtime is recorded, as limph cannot be sure whether the host is available.
Keep in mind that Limph does not do automatic dependancy assignment. You must configure dependancies manually, and Limph will assume that you are indeed familiar with your network's topology.
Notifications
Notifications come in two flavours. Notifications of individual host transitions are sent to all users who have thew Notify box checked, and an hourly digest of the previous hour's activity is sent to all users who have the Digest box checked. Users may be part of both groups, or neither. Notification settings may only be altered by users with Admin rights.
Ephemera
Internals
Poller
In order to make sure that all the requested checks get done each minute and don't run over each other, the Limph poller uses unix-style forking to divide the hosts up into groups and check them in parallel. This is somewhat complicated by the necessity of checking the hosts on which other hosts depend first, but extensive testing has been done to ensure that the tree is walked properly.
If you find, while using Limph, that resource utilization is getting out of hand due to a large number of hosts or a deep dependency tree, or both, please contact me via the Sourceforge project page. I'd be curious to see where Limph starts to falter, so I can fix it.
Notes on SQLite
SQLite support is completely untested and has not yet been demonstrated to work. If you want to use Limph with SQLite, and your PHP installation is already known to work with SQLite, please give it a try and contact the developer throught the Sourceforge project page. I am interested in supporting SQLite, but I do not currently have a working PHP/SQLite setup and so cannot test it myself.
SQLite/PDO support is 100% functional.
Fedora
Fedora users may install Limph by simply running "yum install limph" and editing /etc/limph/config.php.
