Transcription
Nagios Version 1.0DocumentationCopyright 1999-2002 Ethan GalstadEmail: nagios@nagios.orgLast Updated: 08-28-2002[ Table of Contents ]Nagios and the Nagios logo are registered trademarks of Ethan Galstad. All other trademarks, servicemarks, registered trademarks,and registered servicemarks mentioned herein may be the property of their respective owner(s). The information contained herein isprovided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN, MERCHANTABILITY, ANDFITNESS FOR A PARTICULAR PURPOSE.
Version 1.0 DocumentationTable of ContentsAboutWhat is Nagios?System requirementsLicensingDownloading the latest versionOther monitoring utilitiesRelease NotesWhat's new in this versionChange logSupportFrequently Asked Questions (FAQs)Mailing listsContract helpGetting StartedAdvice for beginnersInstalling NagiosCompiling and installing NagiosSetting up the web interfaceConfiguring Nagios
Configuration overviewMain configuration file optionsObject configuration file optionsCGI configuration file optionsConfiguring authorization for the CGIsExtended information configurationRunning NagiosVerifying the configurationStarting NagiosStopping and restarting NagiosNagios PluginsStandard pluginsWriting your own pluginsNagios Addonsnrpe - Daemon and plugin for executing plugins on remote hostsnsca- Daemon and client program for sending passive check results across the networkTheory Of OperationDeterming status and reachability of network hostsNetwork outagesNotificationsPlugin theoryService check schedulingState typesTime periodsAdvanced TopicsEvent handlersExternal commandsIndirect host and service checksPassive service checksVolatile servicesService result freshness checksDistributed monitoringRedundant and failover monitoring
Detection and handling of state flappingService check parallelizationNotification escalationsMonitoring service and host clustersHost and service dependenciesState stalkingPerformance dataScheduled host and service downtimeDatabase supportUsing the embedded Perl interpreterObject inheritence using template-based config dataTime-saving tips for templated-based object definitionsIntegration With Other SoftwarePortsentrySNMP TrapsTCP WrappersMiscellaneousSecuring NagiosTuning Nagios for maximum performanceUsing macros in commandsInformation on the CGIsCustom CGI headers and footers
About NagiosTMWhat Is This?NagiosTM is a system and network monitoring application. It watches hosts and services that you specify,alerting you when things go bad and when they get better.NagiosTM was originally designed to run under Linux, although it should work under most other unices as well.For more information on what operating systems Nagios will and will not run under, see the OS ports page athttp://www.nagios.org/ports.shtml.Some of the many features of NagiosTM include: Monitoring of network services (SMTP, POP3, HTTP, NNTP, PING, etc.)Monitoring of host resources (processor load, disk usage, etc.)Simple plugin design that allows users to easily develop their own service checksParallelized service checksAbility to define network host hierarchy using "parent" hosts, allowing detection of and distinctionbetween hosts that are down and those that are unreachableContact notifications when service or host problems occur and get resolved (via email, pager, or userdefined method)Ability to define event handlers to be run during service or host events for proactive problem resolutionAutomatic log file rotationSupport for implementing redundant monitoring hostsOptional web interface for viewing current network status, notification and problem history, log file, etc.System RequirementsThe only requirement of running Nagios is a machine running Linux (or UNIX variant) and a C compiler. Youwill probably also want to have TCP/IP configured, as most service checks will be performed over the network.You are not required to use the CGIs included with Nagios. However, if you do decide to use them, you willneed to have the following software installed.1. A web server (preferrably Apache)2. Thomas Boutell's gd library version 1.6.3 or higher (required by the statusmap and trends CGIs)LicensingNagiosTM is licensed under the terms of the GNU General Public License Version 2 as published by the FreeSoftware Foundation. This gives you legal permission to copy, distribute and/or modify Nagios under certainconditions. Read the 'LICENSE' file in the Nagios distribution or read the online version of the license for more
details.NagiosTM is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN,MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.AcknowledgementsSeveral people have contributed to Nagios by either reporting bugs, suggesting improvements, writing plugins,etc. A list of some of the many contributors to the development of Nagios can be found athttp://www.nagios.org.Downloading The Latest VersionYou can check for new versions of Nagios at http://www.nagios.org.Other Monitoring UtilitiesIn case you weren't aware, there are other network monitoring utilities available besides Nagios. I think Nagiosis a pretty good contender, but I'm obviously biased. Here are links to a few other free monitoring utilities. Thereare many others that are not listed here - search the net (or Freshmeat) and you'll find them. Angel Network MonitorAutostatusBig BrotherHiWAySMARSMonNetup ngSysmonNagios and the Nagios logo are trademarks of Ethan Galstad. All other trademarks, servicemarks, registered trademarks, and registered servicemarks may be theproperty of their respective owner(s).
What's New in Version 1.0Important: Make sure you read through the documentation (especially the FAQs) before sending a question tothe mailing lists.Many of the changes described below are the direct result of this project being renamed from NetSaint.Transitioning from NetSaint to Nagios will undoubtedly take some time, but it'll be well worth it.Change LogThe change log for Nagios can be found online at http://www.nagios.org or in the Changelog file in the rootdirectory of the source code distribution.Changes1. User/Group Change. The default user/group that Nagios runs under is now nagios/nagios.2. Directory Change. The default directory that Nagios gets installed in is now /usr/local/nagios.3. URL Changes. The base URLs for accessing the HTML files and CGIs through the web interface arenow /nagios/ and /nagios/cgi-bin/, respectively.4. Config File Changes. The main config file is now nagios.cfg and the CGI config file is now cgi.cfg.5. Process Check Command Changes. The old process check command variable in the CGI config filehas been renamed to nagios check command. Also, if you do not specify a check command, the CGIswill assume the Nagios process is running properly.6. Archive Changes. Archived log files from Netsaint must be renamed from "netsaint-date.log" format to"nagios-date.log" format if you want to make them available to the Nagios CGIs. You can rename allyour archived log files with the following command (assuming you've already moved them to their newdirectory location): rename netsaint nagios netsaint*.log7. Retention File Format Change. The format of the retention file (or database, if that's what you wereusing) has changed to support more variables. No conversion utility is yet available, which means you'lleither have to find a way to manually convert your retention data, or lose it when you make thechangeover.8. Database Schema Changes. The database schema for status, retention, comment, and extendedinformation data has changed. If you were using database support previously, you'll either have torecreate the databases using the sample scripts provided in the contrib/database directory just alteryour existing tables (an exercise which will be left to you). Also note that the default database name isnow nagios.New Features
1. Template-Based Object Config File. This is probably the biggest feature which has been added. Useof the template-based object config file format is optional, but highly recommended. Note that the olderconfig file format is still supported if you really want it. The template-based config file is much easier toread, modify, and expand upon compared to the older format. It also allows you to specify host- andservice-specific values for things like flap detection thresholds, flap detection and performance dataprocessing options, etc. If you're interested in trying out the new template-based config file format,check out the convertcfg utility in the contrib/ directory of the distribution - it can be used to quicklyconvert your old config files to the template-based format. More information on the template-basedobject config file can be found here.2. Template-Based Extended Info Config File. This is similar to the template-based object configurationfile format mentioned above. You can now store extended host and service information in a templatebased config file. More information on doing this can be found here. If you wish, you can still use theolder style of defining extended information directives in the CGI configuration file as described here.3. Host Dependencies. You can now define optional host dependencies which will prevent notificationsfrom being sent out for a host if one or more criteria fail. In the past there have been implicitdependencies between hosts that are related through "parenting", but this now allows you to createexplicit dependencies between unrelated hosts. More information on dependencies can be found here.4. Host Escalations. You can now define optional notification escalations for specific hosts. In the pastyou were only able to define escalations for entire hostgroups. While this was closely matched to nonescalated notification logic, it didn't provide much flexibility. Note that hostgroup escalations are stillsupported and can be used in conjunction with host escalations. More information on notificationescalations can be found here.5. Freshness Checking. Nagios now internally handles the concept of "freshness checking" of servicecheck results. If freshness checking is enabled for a particular service, Nagios will force an active checkof that service if the results from the last check are "stale" or "too old" (as determined by a threshold youspecify). This makes implementing distributed monitoring servers much simpler, as you don't need anadditional addon to make sure service results are "fresh". More information on how freshness checkingworks can be found here.6. Scheduled Downtime. Scheduled downtime for hosts and service is now retained across programstarts. Additionally, you can now distinguish between "fixed" and "flexible" downtime. Fixed downtimestarts and stops at absolute times, while flexible downtime starts when a host or service first goes into aproblem state. More information on scheduled downtime can be found here.7. State Stalking. You can now enable "stalking" for different states on a per-host or per-service basis.Stalking provides you with more information about problems when you're analyzing archived log data.More information on state stalking can be found here.8. File-Based Performance Data Processing. Nagios can now be compiled to dump performance datadirectly to a file in a format you define. This method is must faster and requires far less overhead thatthe default method of processing performance data. More information on the file-based option can befound here. General information about performance data can be found here.9. New Histogram CGI. A new histogram CGI has been added. This CGI allows you to see better analyze
when host and service alerts occur over various periods of time.10. New Summary CGI. A new summary CGI has been added. This CGI allows you to generated basicreports about host and service alerts over various periods of time. Reports can be created to show alerttotals, top alert producers, most recent alerts, etc.11. Statusmap CGI Improvements. Several new layout methods have been added to the statusmap CGI.You can also now specify a default layout method with the default statusmap layout directive.12. Availability CGI Improvements. I have made several enhancements to the code in the availabilityCGI, including the ability to separate scheduled downtime from non-scheduled downtime.13. Configuration Directory. You can now specify one or more directories that should be scanned forobject configuration files by using the cfg dir directive. You can use this in conjunction with (or insteadof) the cfg file directive.14. Custom CGI Headers/Footers. You can now include optional headers and footers in the CGIs. This ismost useful if you do custom Nagios installations for customers and want to include tag line, contactinfo, etc in each page. More information on doing this can be found here.15. Cleaning Of Dangerous Macro Output Characters. Potentially dangerous characters can now bestripped from the OUTPUT and PERFDATA macros before they're used in notification commands,etc. by using the illegal macro output chars directive. At a bare minimum, I highly recommend youstrip out the characters shown in the example, or an attacker might be able to execute arbitrarycommands as the nagios user!
Frequently Asked Questions (FAQs)Online FAQ DatabaseA searchable FAQ database can now be found online at http://www.nagios.org/faqs.
Advice for BeginnersCongrats on choosing to try Nagios! Nagios is quite powerful and flexible, but unfortunately its not very friendlyto newbies. Why? Because it takes a lot of work to get it installed and configured properly. That being said, ifyou stick with it and manage to get it up and running, you'll never want to be without it. :-) Here are some veryimportant things to keep in mind for those of you who are first-time users of Nagios:1. Relax - its going to take some time. Don't expect to be able to compile Nagios and start it up right offthe bat. Its not that easy. In fact, its pretty difficult. If you don't want to spend time learning how thingswork and getting things running smoothly, don't bother using this software. Instead, pay someone tomonitor your network for you or hire someone to install Nagios for you. :-)2. Read the documentation. Nagios is difficult enough to configure when you've got a good grasp ofwhat's going on, and nearly impossible if you don't. Do yourself a favor and read before blindlyattempting to install and run Nagios. If you're the type who doesn't want to take the time to read thedocumentation, you'll probably find that others won't find the time to help you out when you haveproblems. RTFM.3. Use the sample config files. Sample configuration files are provided with Nagios. Look at them,modify them for your particular setup and test them! The sample files are just that - samples. There's avery good chance that they won't work for you without modifications. Sample config files can be found inthe sample-config/ subdirectory of the Nagios distribution.4. Seek the help of others. If you've read the documentation, reviewed the sample config files, and arestill having problems, try sending a descriptive email message describing your problems to the nagiosusers mailing list. Due to the amount of work that I have to do for this project, I am unable to answermost of the questions that get sent directly to me, so your best source of help is going to be the mailinglist. If you've done some background reading and you provide a good problem description, odds are thatsomeone will give you some pointers on getting things working properly.
Installing NagiosImportant: Installing and configuring Nagios is rather involved. You can't just compile the binaries, run theprogram and sit back. There's a lot to setup before you can actually start monitoring anything. Relax, take yourtime and read all the documentation - you're going to need it. Okay, let's get started.Unpacking The DistributionTo unpack the Nagios distribution, type the following two commands at a shell prompt:gunzip nagios-1.0.tar.gztar xf nagios-1.0.tarIf you downloaded the ZIP version of the distribution, type the following:unzip nagios-1.0.zipWhen you have finished executing these commands, you should find a nagios-1.0 directory that has beencreated in your current directory. Inside that directory you will find all the files that compromise the core Nagiosdistribution.Create Installation DirectoryCreate the base directory where you would like to install Nagios as follows.mkdir /usr/local/nagiosCreate User/GroupYou're probably going to want to run Nagios under a normal user account, so add a new user (and group) toyour system with the following commands (these will vary depending on what OS you're running):adduser nagiosRun the Configure ScriptRun the configure script to initialize variables and create a Makefile as follows./configure --prefix prefix --with-cgiurl cgiurl --with-htmurl htmurl --with-nagios-user someuser --withnagios-grp somegroup Replace prefix with the installation directory that you created in the step above (default is
/usr/local/nagios)Replace cgiurl with the actual url you will be using to access the CGIs (default is /nagios/cgi-bin). DoNOT append a slash at the end of the url.Replace htmurl with the actual url you will be using to access the HTML for the main interface anddocumentation (default is /nagios/)Replace someuser with the name of a user on your system that will be used for setting permissions onthe installed files (default is nagios)Replace somegroup with the name of a group on your system that will be used for setting permissionson the installed files (default is nagios)Compile BinariesCompile Nagios and the CGIs with the following command:make allInstalling The Binaries And HTML FilesInstall the binaries and HTML files (documentation and main web page) with the following command:make installInstalling An Init ScriptIf you wish, you can also install the sample init script to /etc/rc.d/init.d/nagios with the following command:make install-initYou may have to edit the init script to make sense with your particular OS and Nagios installation by editingpaths, etc.Directory Structure And File LocationsChange to the root of your Nagios installation directory with the following command.cd /usr/local/nagiosYou should see five different subdirectories. A brief description of what each directory contains is given in thetable below.Sub-Directory Contentsbin/Nagios core programetc/Main, resource, object, and CGI configuration files should be put here
sbin/CGIsshare/HTML files (for web interface and online documentation)var/Empty directory for the log fileInstalling The PluginsIn order for Nagios to be of any use to you, you're going to have to download and install some plugins. Pluginsare usually installed in the libexec/ directory of your Nagios installation (i.e. /usr/local/nagios/libexec). Pluginsare scripts or binaries which perform all the service and host checks that constitute monitoring. You can grabthe latest release of the plugins from the Nagios downloads page or directly from the SourceForge projectpage.Setup The Web InterfaceYou're probably going to want to use the web interface, so you'll also have to read the instructions on setting upthe web interface and configuring web authentication, etc. next.Configuring NagiosSo now you have things compiled and installed, but you still haven't configured Nagios or defined objects(hosts, services, etc.) that should be monitored. Information on configuring Nagios and defining objects can befound here. There's a lot to configure, but don't let it discourage you - its well worth it.
Setting Up The Web InterfaceNotesIn these instructions I will assume that you are running the Apache web server on your machine. If you areusing some other web server, you'll have to make changes where appropriate. I am also assuming that youuse
What's New in Version 1.0 Important: Make sure you read through the documentation (especially the FAQs) before sending a question to the mailing lists. Many of the changes described below are the direct result of this project being renamed from NetSaint. Transitioning from NetSaint to Nagios will undoubtedly take some time, but it'll be well worth it.
