INSTALL

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

2.0 now requires IPv6 *libraries*, but IPv6 doesn't need to be configured.
If you plan to really *use* IPv6, please read the note at the end.

On all hosts:

- A reasonable Perl 5 (ie: at least 5.8)

- 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.  Any web server supporting simple file service and
  CGI or Fast CGI should work. Apache HTTPD should be suitable.  Also
  reported to be working is nginx and lighttpd, please contribute your
  configs.

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

  RRD version 1.4.6 or greater is recommended. Munin will work in
  general with RRD 1.2, but you will experience performance issues,
  and graphing will fail in certain corner cases.

- Perl modules for server: 
   - Time::HiRes
   - Storable
   - Digest::MD5,
   - HTML::Template
   - Text::Balanced
   - Params::Validate
   - TimeDate
   - Net::SSLeay if you want to use SSL/TLS
   - Getopt::Long
   - File::Copy::Recursive
   - CGI::Fast
   - IO::Socket::INET6
   - Log::Log4perl 1.18 or later (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 CentOS), Fedora, Debian, Ubuntu, SuSE and others will have quite
a few of these packages available to install with their standard
install tools so there is no need to install from the source
distribution unless you want a Munin release that is not packaged.


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 install munin from /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 and plugiuns on the nodes.

To install both master and node:

   	- Review/edit Makefile.config to suit 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

	- For graphing you have to use CGI now. You usually want to use FastCGI
	  graphing unless you have a quite small munin and a quite fast 
	  server. More information is available at 
	  http://munin-monitoring.org/wiki/CgiHowto2

	  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 some OS/distribution-specific scripts.


To install a node:

	- Edit Makefile.config to suit your needs.

	- Create the user and group "munin".  The use can have a
          nologin shell.

	- 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.  Restart it
	  it it was already started.  The node only discovers new plugins
	  when it is restarted.

	  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).

If you want to use SSH to contact the node from the master (rather
than over tcp port 4949) please refer to
http://munin-monitoring.org/wiki/Native_ssh

For further build alternatives, see Makefile.


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.  Example to show plugins it would
enable:

  munin-node-configure --suggest

To enable those:

  munin-node-configure --shell | sh -x

You can also just run munin-node-configure --shell and paste the
commands you want into a shell.

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

Whenever the installed plugins changes, the node needs to be
restarted. Also restart the node when you change it's configuration.

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.

IPv6
====

The basic problem with munin and ipv6 is that we use Net::Server and
there has been no releases of Net::Server supporting IPv6
(pr. 2011-07-22).  So we've found out that Debian has patches for IPv6
support and they're even claiming to be complete - and our testing
agrees. We (janl) have submitted a new version of Net::Server to CPAN 
based on this.

If you use Debian (or derivates) with Net::Server 0.99-2 or later or
if you find Net::Server 0.99.6.1 or more recent in your CPAN or
Distribution repository is probably supports IPv6 out of the box.

In the mean time look in the contrib directory for our
Net::Server.patch.  You can apply this directly to your installed
Net::Server perl modules - this is a bit dirty, and you may have to
jigger the directory paths a bit, but it will work.  If you use CPAN
anyway then get Net::Server and apply the patch provided.

If your Net::Server understands IPv6 and you have "host *" in your
munin-node.conf file your munin will be listening on a dual ipv4/ipv6
socket and you can connect to it with "telnet ::1 4949" to test.  You
probably need to correct your allow list like so:

  allow \:\:1$

to actually allow this.  If you keep an eye on munin-node.log then the
cause of any problems should be obvious.