netdisco-frontend 1.0-2 / usr / share / netdisco / html / doc / UPGRADE.html

<%text>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#author">AUTHOR</a></li>
	<li><a href="#support">SUPPORT</a></li>
	<li><a href="#upgrading">UPGRADING</a></li>
	<li><a href="#version_specific_notes">VERSION SPECIFIC NOTES</a></li>
	<li><a href="#application_notes">APPLICATION NOTES</a></li>
	<ul>

		<li><a href="#apache___mod_perl">Apache / Mod_perl</a></li>
		<li><a href="#snmp__info">SNMP::Info</a></li>
	</ul>

	<li><a href="#general_upgrade_procedures">General Upgrade Procedures</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Netdisco UPGRADE - Instructions on Upgrading between versions.</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Max Baker</p>
<p>
</p>
<hr />
<h1><a name="support">SUPPORT</a></h1>
<p>See <a href="INSTALL.html">the INSTALL manpage</a> or <a href="README.html">the README manpage</a> or <a href="http://netdisco.org">http://netdisco.org</a></p>
<p>
</p>
<hr />
<h1><a name="upgrading">UPGRADING</a></h1>
<p>Here are some hints for upgrading between versions of Netdisco.</p>
<p><strong>FIRST!</strong> Go read below where it says <a href="#backup_database">Backup Database</a> and <a href="#backup_configuration_files">Backup Configuration Files</a>
and <strong>DO IT!</strong>.</p>
<p>The <strong>best way</strong> is to back everything up, move the configuration
files out of the way and then follow <em>INSTALL</em> for all but the
database steps.</p>
<p>Then change the configuration files back to match.  If you reuse your old configuration file,
check it against the new one to see what config file directives have been added / removed / changed.</p>
<p>You <strong>DO NOT</strong> wipe the database contents for an upgrade.  But just in case, you will have
of course made a backup by now.</p>
<p>Make sure to read the <code>section(s)</code> relevant to your version update in
<a href="#version_specific_notes">VERSION SPECIFIC NOTES</a>, then read the <a href="#application_notes">APPLICATION NOTES</a> and <a href="#general_upgrade_procedures">General Upgrade Procedures</a>
sections.</p>
<p>
</p>
<hr />
<h1><a name="version_specific_notes">VERSION SPECIFIC NOTES</a></h1>
<dl>
<dt><strong><a name="item_1">v0.95 -&gt; 1.0</a></strong>

<dl>
<dt><strong><a name="item_new_perl_modules">New Perl Modules</a></strong>

<dd>
<pre>
  Parallel::ForkManager
  Net::LDAP (optional for LDAP authentication)
  Net::SSLeay (optional for encrypted LDAP authentication)
  IO::Socket::SSL (optional for encrypted LDAP authentication)</pre>
</dd>
<dt><strong><a name="item_update_database">Update Database</a></strong>

<dd>
<p>You will have to run the following command to add new tables and modify existing
ones.</p>
</dd>
<dd>
<pre>
 cd /usr/local/netdisco/sql
 ./pg upgrade-0.95-to-1.0.sql</pre>
</dd>
<dd>
<p>Note that it is safe to run the upgrade.sql scripts more than once (in case you are
running a CVS or RC version). Also note that if you are upgrading from 0.94,
you must run <code>upgrade-0.94-to-0.95.sql</code> first.</p>
</dd>
</li>
</dl>
<dt><strong><a name="item_0">v.0.94 -&gt; 0.95</a></strong>

<dl>
<dt><strong><a name="item_new_and_updated_perl_modules">New and Updated Perl Modules</a></strong>

<dd>
<p>This version of Netdisco is based around the new API for the Graph module, so you need 
to have version 0.50 or greater and GraphViz 2.02 or greater.</p>
</dd>
<dd>
<p>Also we are now using the Net::NBName module to scan nodes for netbios information, 
and this module must be installed.</p>
</dd>
<dd>
<pre>
 perl -MCPAN -e shell
        install Net::NBName
        install Graph
        install GraphViz</pre>
</dd>
<dd>
<p>You should update all the Perl modules listed in <em>INSTALL</em> as well.</p>
</dd>
</li>
<dt><strong><a name="item_snmp_3a_3ainfo">SNMP::Info</a></strong>

<dd>
<p>Please make sure you have the newest verison of SNMP::Info available, version
1.04 minimum.</p>
</dd>
<dd>
<pre>
 perl -MCPAN -e shell
        install SNMP::Info</pre>
</dd>
</li>
<dt><strong><a name="item_new_sql_script">New SQL script</a></strong>

<dd>
<p>The <em>pg_all</em>, <em>pg_init</em>, <em>pg_back</em>, and <em>pg_run</em> commands have been
rolled into one new command : <code>sql/pg</code>.  This new command will read the
command line for arguments and then parse <em>netdisco.conf</em> for the database
user and password.  Run <code>sql/pg --help</code> for more options.</p>
</dd>
</li>
<dt><strong><a name="item_database_upgrades">Database Upgrades</a></strong>

<dd>
<p>Now would be a great time to upgrade to Postgres 8.x if you haven't already.
There are some major speed, memory, and storage benefits, and there is no INDEX
bloat problem.  Upgrading from 7.x does require a data base dump/restore.  See
Postgres documentation and the <code>sql/pg_dump</code> command that you already used to
make a backup.  Follow the instructions in INSTALL and re-install the database
related Perl modules after changing versions.</p>
</dd>
<dd>
<p>You will have to run the following command to add new tables and modify existing
ones.</p>
</dd>
<dd>
<pre>
 cd /usr/local/netdisco/sql
 ./pg upgrade-0.94-to-0.95.sql</pre>
</dd>
<dd>
<p>Note that it is safe to run the upgrade.sql scripts more than once (in case you are
running a CVS or RC version). Also note that if you are upgrading from 0.93 or older,
you must run <code>upgrade-0.93-to-0.94.sql</code> first.</p>
</dd>
</li>
<dt><strong><a name="item_security_warning">Security Warning</a></strong>

<dd>
<p><strong>WARNING</strong>!  There is a potential community string exposure when Netdisco is auto-discovering
network equipment.  If a malicious host were to implement CDP and Netdisco were
to discover that host, Netdisco would send all read-only community strings to
that device in an attempt to add it to the topology.</p>
</dd>
<dd>
<p>To avoid this problem, limit the address range that netdisco will discover
or disable CDP and similar discovery protocols from your end-ports.
Be aware that in configurations with IP phones, CDP may be necessary for
certain aspects of phone support.  See <a href="README.html#security_warning">Security Warning in the README manpage</a> for
more information.</p>
</dd>
</li>
</dl>
<dt><strong>v0.93 -&gt; 0.94</strong>

<dl>
<dt><strong><a name="item_autodetection_of_uplink_ports">Autodetection of Uplink Ports</a></strong>

<dd>
<p>Macsuck will now autodetect some uplink ports.  If it sees the MAC addres of a
known switch port or router, it will not collect mac addresses on that port.</p>
</dd>
<dd>
<p>Start checking the logs from your macwalk device (you can do it from the web
page now) and look for the uplink warnings.  Fix your topology file to match.</p>
</dd>
</li>
<dt><strong>SNMP::Info</strong>

<dd>
<p>You will need SNMP::Info v0.9 in order to support the new netdisco-mibs package.</p>
</dd>
</li>
<dt><strong>Database Upgrades</strong>

<dd>
<p>Now would be a great time to upgrade to Postgres 7.4 if you haven't already.  
There are some great speed benefits, and there is no INDEX bloat problem.  Upgrading
from 7.2 or 7.3 does require a data base dump/restore.  See Postgres documentation.</p>
</dd>
<dd>
<p>You will have to run the following command to add new tables and modify existing
ones.</p>
</dd>
<dd>
<pre>
 cd /usr/local/netdisco/sql
 ./pg_run upgrade-0.93-to-0.94.sql</pre>
</dd>
<dd>
<p>Note that it is safe to run the upgrade.sql scripts more than once (in case you are
running a CVS or RC version).</p>
</dd>
</li>
<dt><strong><a name="item_graphviz">GraphViz</a></strong>

<dl>
<dt><strong><a name="item_program">Program</a></strong>

<dd>
<p>Make sure you have a relatively new version.  If you get an error similar to</p>
</dd>
<dd>
<pre>
  Creating CMAP : /usr/local/netdisco/html/netmap.map
    warning, language cmap not recognized, use one of: ps hpgl pcl mif...</pre>
</dd>
<dd>
<p>You need a newer version of GraphViz</p>
</dd>
</li>
<dt><strong><a name="item_graphviz_2epm_2_2e01">GraphViz.pm 2.01</a></strong>

<dd>
<p>The newest Perl interface to GraphViz (non-dependent on the GraphViz 
release) has some better client map interfaces for the Network Graph.</p>
</dd>
<dd>
<p>Please make sure this newest version is installed.</p>
</dd>
<dd>
<pre>
 perl -MCPAN -e shell
    install GraphViz</pre>
</dd>
<dd>
<p>Double check the version.</p>
</dd>
<dd>
<pre>
 perl -MGraphViz -e 'print $GraphViz::VERSION'</pre>
</dd>
</li>
</dl>
<dt><strong><a name="item_perl_modules">Perl Modules</a></strong>

<dd>
<p>A lot of the Perl modules that Netdisco depends on have released newer (better) versions.
Go to the INSTALL and follow Part 8.1 <code>Perl Modules and Mason</code>.   If you use CPAN, it will
upgrade all the dependency modules for you too.</p>
</dd>
</li>
<dt><strong><a name="item_bay_switches">Bay Switches</a></strong>

<dd>
<p>If you have bay switches, note that the naming scheme for the ports has changed
from <a href="#item_1"><code>1</code></a> to <code>1.1</code> as they were folded into the new Nortel classes.  The above
upgrade script will do the renaming for you, so you won't lose data.</p>
</dd>
</li>
</dl>
<dt><strong>v0.92 -&gt; 0.93</strong>

<dl>
<dt><strong><a name="item_graphviz_0_2e10">GraphViz 0.10</a></strong>

<dd>
<p>You may want to install this latest version of GraphViz</p>
</dd>
</li>
<dt><strong>Database Upgrades</strong>

<dd>
<p>For some of the new features, fields have been added to some
of the database tables.  A <em>.sql</em> file has been made to make
the changes for you.   Please run :</p>
</dd>
<dd>
<pre>
 cd /usr/local/netdisco/sql
 ./pg_run upgrade-0.92-to-0.93.sql</pre>
</dd>
<dd>
<p>IGNORE the warning about nuking all the data in the table. It won't.
But even if you did, YOU ALREADY MADE A BACKUP RIGHT? (<code>sql/pg_back</code>)</p>
</dd>
</li>
<dt><strong><a name="item_new_mib_files">New MIB Files</a></strong>

<dd>
<p>If you insist on using this old version of netdisco, at least download
the <code>netdisco-mibs</code> package and use that.</p>
</dd>
</li>
</dl>
<dt><strong>v0.91 -&gt; 0.92</strong>

<dd>
<p>Make sure you run <code>Database Cleanup</code>  or <code>-K</code> when you 
are done upgrading.  The bug where the MAC address of switch
ports showing up on their own port has been fixed.  SNMP::Info
Version 0.7 required.</p>
</dd>
</li>
<dt><strong>v0.90 -&gt; 0.91</strong>

<dl>
<dt><strong><a name="item_netdisco_apache_2econf">netdisco_apache.conf</a></strong>

<dd>
<p>Double check that your copy of netdisco_apache.conf has the 
settings right for all the <code>session_*</code> directives.</p>
</dd>
</li>
<dt><strong>GraphViz</strong>

<dd>
<p>Make sure you have GraphViz 0.9 installed.</p>
</dd>
</li>
</dl>
</dl>
<p>
</p>
<hr />
<h1><a name="application_notes">APPLICATION NOTES</a></h1>
<p>
</p>
<h2><a name="apache___mod_perl">Apache / Mod_perl</a></h2>
<p>You shouldn't have to upgrade apache, but now would be a good time to
see if there are any security upgrades to apache or mod_perl.</p>
<p>
</p>
<h2><a name="snmp__info">SNMP::Info</a></h2>
<p>When upgrading to any version, please make sure you have the
newest version of SNMP::Info installed (at least 2.01):</p>
<dl>
<dt><strong><a name="item_cvs_version">CVS Version</a></strong>

<dd>
<p>To update a CVS version of SNMP::Info :</p>
</dd>
<dd>
<pre>
    cd /usr/local/netdisco/SNMP
    cvs update</pre>
</dd>
</li>
<dt><strong><a name="item_cpan_version">CPAN Version</a></strong>

<dd>
<p>To update a version installed by CPAN :</p>
</dd>
<dd>
<pre>
    perl -MCPAN -e shell
    install SNMP::Info</pre>
</dd>
</li>
<dt><strong><a name="item_manual_install_version">Manual Install Version</a></strong>

<dd>
<p>Download the newest version from CPAN or <a href="http://snmp-info.sourceforge.net">http://snmp-info.sourceforge.net</a>
and install.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="general_upgrade_procedures">General Upgrade Procedures</a></h1>
<dl>
<dt><strong><a name="item_read_install">Read INSTALL</a></strong>

<dd>
<p>Read the INSTALL file that comes with the new version to see
what has changed.  Make sure you have all the Requirements
listed.</p>
</dd>
</li>
<dt><strong><a name="item_backup_database">Backup Database</a></strong>

<dd>
<p>For any version you will want to make backup copies of all your 
data first.</p>
</dd>
<dd>
<pre>
    cd /usr/local/netdisco/sql
    ./pg --back
    scp db_back*.gz somesafehost:</pre>
</dd>
</li>
<dt><strong><a name="item_backup_configuration_files">Backup Configuration Files</a></strong>

<dd>
<p>Make backups of all your files.</p>
</dd>
<dd>
<pre>
    tar cvf - -C /usr/local netdisco | gzip &gt; netdisco-back.tgz
    scp netdisco-back.tgz somesafehost:
    cp /usr/local/netdisco/*.conf /path/to/some_where_safe
    cp /usr/local/netdisco/*.txt  /path/to/some_where_safe</pre>
</dd>
</li>
<dt><strong><a name="item_vacuum_full_and_reindex_database">Vacuum full and reindex database</a></strong>

<dd>
<p>For PostgreSQL you may be suffering from severe space and
performance problems because of various issues.  Especially for 
versions before 7.4.  Please consider upgrading to 8.x and ALSO
run the Procedure, ``Things are Getting Really Slow'' in README.</p>
</dd>
<dd>
<p>This will REINDEX and VACUUM FULL your database.</p>
</dd>
<dd>
<p>On a recent Postgres 7.3 install this changed the database size from
16GB to 400 MB!   Sound worth it?</p>
</dd>
</li>
<dt><strong><a name="item_install_on_top_of_existing_netdisco">Install on top of existing Netdisco</a></strong>

<dd>
<p>Put the new files in your <em>netdisco/</em> directory</p>
</dd>
<dd>
<pre>
    cp -R /path/to/netdisco-new-0.999 /usr/local/netdisco</pre>
</dd>
</li>
<dt><strong><a name="item__5boptional_5d_upgrade_perl_modules">[Optional] Upgrade Perl Modules</a></strong>

<dd>
<p>Following the procedures in <em>INSTALL</em>, now would be a good time
to upgrade all the required Perl modules.</p>
</dd>
<dd>
<p>This step is optional, unless a certain Perl module is listed for 
your version.</p>
</dd>
</li>
<dt><strong><a name="item_check_permissions">Check Permissions</a></strong>

<dd>
<p>Make sure the permissions are set to let the web user
read the <em>html/</em> directory and write to the <em>mason/</em> directory.</p>
</dd>
</li>
<dt><strong><a name="item_modify_the_configuration_files">Modify the Configuration Files</a></strong>

<dd>
<p>New options are always being added to the config files and 
Netdisco.  It's usually a lot cleaner to modify the new config
file that comes with Netdisco than try to add the new features
to the old one.  This helps get rid of old bugs too.</p>
</dd>
</li>
<dt><strong><a name="item_restart_apache">Restart Apache</a></strong>

<dd>
<p>You must do a full restart on apache (not a <code>graceful</code> or <code>restart</code>) so that Netdisco
will use the newly installed version of <em>netdisco.pm</em>.</p>
</dd>
<dd>
<pre>
    /usr/local/apache/bin/apachectl stop
    /usr/local/apache/bin/apachectl start</pre>
</dd>
</li>
<dt><strong><a name="item_restart_admin_daemon">Restart Admin Daemon</a></strong>

<dd>
<p>You need to restart the admin daemon to run on the new copy of Netdisco.</p>
</dd>
<dd>
<pre>
    su - netdisco -c &quot;/usr/local/netdisco -p restart&quot;</pre>
</dd>
</li>
<dt><strong><a name="item_reload_crontab">Reload Crontab</a></strong>

<dd>
<p>Review <em>netdisco.crontab</em> and reload it for the <code>netdisco</code> user.</p>
</dd>
<dd>
<pre>
    su 
    crontab -u netdisco /usr/local/netdisco/netdisco.crontab</pre>
</dd>
</li>
</dl>

</%text>