Upgrading to 1.4
================

Upgrading from the Munin 1.2 series to 1.4 should be quite easy.  But
there are some things to take note of if you want a very smooth
transition.

If you install from SVN or tar ball please make sure you read the
INSTALL file VERY carefuly.  There are new package dependencies and
some bugs in the install process are noted there.

From Munin 1.2 in general
-------------------------

Based on comparisons of a few (very few) Munin installations on Linux
we see identical rrd file names, and rrd files are created and
structured the same way as before.  This ensures that your data
history is preserved.  Upgrading to 1.4 should therefore prove to be
straightforward and cause no data loss. BUT! There are a few
exceptions noted below.

In terms of ordering I would upgrade the master first.  If you do not
use a packaging system you may have to look around for old .pm files
and purge them to get 1.4 to work propperly.  Do NOT purge the RRD
files or the configuration.

After the master is upgraded upgrade the nodes one by one.  Please see
notes about changes in plugin and data-field names in the sections
below before you start upgrading the nodes.

Changes in default paths
------------------------

If you do not use a packaging system please review Makefile.config and
after doing "make" the example munin.conf and note changes in default
paths, which you may or may not like, and if you do not keep the new
default htmldir you may want to edit Makefile.config, or alternatively
take a look at the .htaccess file installed in the default htmldir to
restrict public access to your munin (as described in the INSTALL
file)

From Munin 1.2.6
----------------

If you have munin-nodes running 1.2.6 then some of the plugins use
short (truncated) field names.  Especially the Linux df plugin will be
using truncated fieldnames for some disk devices.  This is due to a
basing a bug fix on obsolete documentation.  The device names were
limited to 19 characters, only the 19 last characters of the device
name was used.  This truncation is done by the plugin on the node.
When the plugin/node is upgraded the truncation stops.

There is no really reliable way to fix this or migrate automatically.
What you can do is install 1.4.0 on one node at a time, and for each
upgrade examine your rrd file names.  You should be able to identify
rrd files for the upgraded node that have nearly identical names.
Personally I would use a graphical file browser for this.  If you find
two files that should be one then the one with the longest filename
should be newest, and the one with the short file name should not have
been updated since the node upgrade.  Rename the file with the short
name so that it has the long name.

On Solaris
----------

Some plugin renamings to get the name aligned with the other
platforms:
- if_errcoll_ is now called if_err_
- fs_df is now called df
- fs_inodes is now called df_inodes

You can simply rename the rrd files according to this (or you can
rename the plugins, but that will be a uphill battle, they'll be
renamed back when you upgrade the next time).  Note that the plugins
will change names as you upgrade and auto-configure your nodes, not
when you upgrade the munin-master.


Users of Munin 1.2 in combination with NMSes
--------------------------------------------

There are two issues that have been reported.

Users of Munin in combination with Nagios have reported that because
some graphs have changed their "graph_title" setting this
dis-associates the tests from the right nagios checks.

Also some plugins do not have default warning and critical levels set
any more (e.g. "load") because the opinions on what is "normal" load
differs widely.  This means that the plugins will not send warning and
critical events to contacts any more.  The warning and critical levels
should be settable for all of these plugins, please use the command
"munindoc <plugin>" on the host where the plugin is installed to see
how to set these levels.

Too audit the differences in warning and critical levels you can make
a copy of the munin file called "datafile" before upgrading (or get
one from backup), and use egrep to get a listing of the settings prior
to update:

  egrep '(warning|critical)' datafile.old

and again on the post-upgrade datafile to compare the lists so you can
specify the ones you need.
