INSTALL

Munin installation requirements
===============================

On all hosts:

- A reasonable Perl 5

- GNU Make - do not attempt to use any other make (build time only)

- Module::Build - this is part of perl 5.10, for earlier Perls it must
  be installed (build time only)

- The perl module Time::HiRes

- For TLS(SSL) to work you'll need Net::SSLeay everywhere


Server:

- A web server.  Apache HTTPD should be suitable.  Any web server supporting
  simple file service and perhaps CGIs will work.

- RRD with Perl support - this means that RRDs.pm must be available
  and "perl -MRRDs -e ':;'" must run without errors.

- Perl modules for server: 
   - Time::HiRes
   - Storable (needed for ProcessManager.  Should we port datafile to storable too?)
   - Digest::MD5,
   - HTML::Template
   - Text::Balanced
   - Params::Validate
   - TimeDate
   - Net::SSLeay if you want to use SSL/TLS
   - Getopt::Long 2.37 or later
   - Log::Log4perl (which depends on
     - IPC::Shareable
     - Log::Dispatch
     - Log::Dispatch::FileRotate
     - MIME::Lite
     - Mail::Sender
     - Mail::Sendmail
     - MailTools)

   - Developers/packagers: For testing
     - Test::MockModule
     - Test::MockObject
     - Test::Pod::Coverage
     - Test::Perl::Critic 1.096 or later
     - Test::Exception
     - Directory::Scratch (err, wherefrom?)
   
   - As well as all the modules needed on a node - most servers are also
     nodes.

Node:

- Perl modules: Net::Server, Net::Server::Fork, Time::HiRes

- Perl module Net::SNMP for SNMP autoconfiguration and plugins

- For SNMPv3: Perl modules Crypt::DES, Digest::SHA1, Digest::HMAC

- Net::SSLeay if you want to use SSL/TLS

- Perl modules for plugins: Depends on the plugins you want to use,
  but not many.

- If you want to use Java JMX plugins to monitor a Java app: Sun Java
  5+ compiler (a basic JDK Standard Edition from java.sun.com or your
  package system).


If you're missing some Perl modules and they are not in your package
system it's recommended to use the cpan shell (as root) to install the
needed ones.  There is a short cpan shell section at the bottom of
this file if you do not know how to use it.

Please note that BSD and Linux OSes such as Red Hat Enterprise Linux
(and Cent OS), Fedora, Debian, Ubuntu, SuSE and others will have quite
a few of these packages available to install with their standard
install tools.


Installing
==========

NOTE!!!! If you're using NFS please note that the "make install"
process is slightly problematic in that it (Module::Build actually)
writes files under $CWD.  Since "make install" is usually run by root
and root usually cannot write files on a NFS volume, this will fail.
If you use NFS please unpack munin under /var/tmp, /tmp or some such
to work around this.

There are make targets for node, master, documentation and man files.
Generally you want to install everything on the master, and just the
node on ... the nodes.

To install both master and node:

   	- Review/edit Makefile.config to suite your needs.

	- Create the user "munin" and the group "munin" if these are
          not made automatically.  The user needs no shell and no
	  privileges.  On most Linux systems the munin user's shell
	  is the nologin shell (it has different paths on different
          systems - but the user still needs to be able to
          run cron jobs.

	- make (do _NOT_ do "make install" directly, there is a bug
             somewhere that will result in a very defective
             Munin::Common::Defaults to be installed).

	- make install

        - In your HTMLDIR you will now find a .htaccess file with two
          main features:

	  * Password protection. Users/passwords are kept in
	    CONFDIR/munin-httpasswd. Use htpasswd to create/modify
	    users in normal Apache fashion. 

	  * Munin page expiry to refresh contents. This requires
	    mod_expires to be enabled.

	  NOTE: Both these features require the relevant AllowOverride
	  statement in Apache. AuthConfig and Indexes, respectively.

          If you already have a .htaccess file in HTMLDIR it will not
          be overwritten.

	  If you prefer that munin be openly available make the
	  .htaccess file empty to avoid overwriting it later.

	- Review CONFDIR/munin.conf to set up some nodes. At least one
	  node needs to have at least one functional plugin for HTML
	  generation.

	- Create a cron-entry to run "munin-cron" as the user "munin"
	  every 5 minutes.  See build/resources for generic or
          build/dists for distribution-specific scripts.

	- If you want to use the dynamic graphs: Configure the CGI
	  directory, you will find a Apache config example in
	  build/resources.  
	  
	  NOTE: Dynamic graphs are not exactly perfect. Se also
          http://munin.projects.linpro.no/wiki/CgiHowto


To install a node:

	- Edit Makefile.config to suite your needs.

	- Create the group "munin".

	- make

	- make install-common-prime install-node-prime \
          install-plugins-prime

	  NOTE: This overwrites any existing plugins.

	- Decide which plugins to use.  The quick auto-plug-and-play
          solution: 
          munin-node-configure --shell --families=contrib,auto | sh -x

	- Review CONFDIR/munin-node.conf. Ensure that your
	  munin-master can access it.

	- Start the node agent (as root) SBINDIR/munin-node.

	  You probably want to use an init-script instead and you
          might find a good one under build/dists or in the
          build/resources/ directory (maybe you need to edit the init
          script, check the given paths in the script you might use).

For further build alternatives, see Makefile.


Munin-gather
============

Munin-gather is an incomplete work in progress for the server side.
Please ignore it, and if you're a packager certainly don't package
it.


Notes about node plugins
========================

"make install-node-plugins" installs the plugins in LIBDIR (defined in
Makefile.config). Put the ones you want to use (or better yet, create
softlinks) in CONFDIR/plugins/ . An easy way to do this, is the
program "munin-node-configure", using the parameter "--shell". It will
then suggest commands to do this.

Some of the plugins require some configuration to get running.  Some
example configuration files (plugins.conf) is found under the
build/dists directory.

Whenever the plugin list changes, the node needs to be restarted. 

Many OSes and releases thereof have different ways of gathering data.
A lot of OSes still have none.  If you create plugins for an OS/system
which is not already in the package, please send us a copy of them, so
we can add them for others to use.  We'd also be happy if you sent us
any new plugins on systems already in the package.


Using CPAN shell
================

If your OS does not provide all the needed perl packages they can be
intalled by a perl installation tool called CPAN-Shell.  There is
ample documentation about it on the web, but here is a brief tour.

As root execute:

  # perl -MCPAN -e shell

The first time you run this you are interviewed about various things.
Answer the questions, you can probably answer blank on any you do not
understand.

You will then be presented with a CPAN prompt (cpan>) . From this
prompt you type:

  cpan> install Time::HiRes

You could also do it one at a time like this: 

  # perl -MCPAN -e 'install Time::HiRes'

Do the same for all modules needed.  E.g.,

  install Time:HiRes
  install Storable
  install Digest::MD5
  install Text::Balanced

and so on.

If you need to install Munin on a host with no Internet access you can
use CPAN shell on a host _with_ Internet access and use the "get"
command to retrive the needed modules.  One problem: The dependencies
of modules will change over time so the list above may not be correct
6 months after it was last updated.  SO: If you want to make sure you
get all the needed modules you can do a full install of munin on a
Internet connected system and then transfer all the modules to the
non-connected system after.  All the modules that the CPAN shell
retrived can be found like this:

  # cd ~/.cpan/sources
  # find . -name '*.tar.gz
  ./authors/id/G/GA/GAAS/Digest-MD5-2.39.tar.gz
  ...

Now just make sure the sources directory is empty before you begin.