UPGRADE

NAME

    Netdisco UPGRADE - Instructions on Upgrading between versions.

AUTHOR

    Max Baker

SUPPORT

    See INSTALL or README or <http://netdisco.org>

UPGRADING

    Here are some hints for upgrading between versions of Netdisco.

    FIRST! Go read below where it says "Backup Database" and "Backup
    Configuration Files" and DO IT!.

    The best way is to back everything up, move the configuration files out
    of the way and then follow INSTALL for all but the database steps.

    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.

    You DO NOT wipe the database contents for an upgrade. But just in case,
    you will have of course made a backup by now.

    Make sure to read the section(s) relevant to your version update in
    "VERSION SPECIFIC NOTES", then read the "APPLICATION NOTES" and "General
    Upgrade Procedures" sections.

VERSION SPECIFIC NOTES

    v1.1 -> 1.2

        Update Database
            You will have to run the following command to add new tables and
            modify existing ones.

             cd /usr/local/netdisco/sql
             ./pg upgrade-1.1-to-1.2.sql

        SNMP::Info
            Please make sure you have the newest verison of SNMP::Info
            available, version 3.01 minimum.

             perl -MCPAN -e shell install SNMP::Info

        v1.0 -> 1.1

            Update Database
                You will have to run the following command to add new tables
                and modify existing ones.

                 cd /usr/local/netdisco/sql
                 ./pg upgrade-1.0-to-1.1.sql

        v0.95 -> 1.0

            New Perl Modules
                  Parallel::ForkManager
                  Net::LDAP (optional for LDAP authentication)
                  Net::SSLeay (optional for encrypted LDAP authentication)
                  IO::Socket::SSL (optional for encrypted LDAP authentication)

            Update Database
                You will have to run the following command to add new tables
                and modify existing ones.

                 cd /usr/local/netdisco/sql
                 ./pg upgrade-0.95-to-1.0.sql

                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
                "upgrade-0.94-to-0.95.sql" first.

        v.0.94 -> 0.95

            New and Updated Perl Modules
                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.

                Also we are now using the Net::NBName module to scan nodes
                for netbios information, and this module must be installed.

                 perl -MCPAN -e shell
                        install Net::NBName
                        install Graph
                        install GraphViz

                You should update all the Perl modules listed in INSTALL as
                well.

            SNMP::Info
                Please make sure you have the newest verison of SNMP::Info
                available, version 1.04 minimum.

                 perl -MCPAN -e shell
                        install SNMP::Info

            New SQL script
                The pg_all, pg_init, pg_back, and pg_run commands have been
                rolled into one new command : "sql/pg". This new command
                will read the command line for arguments and then parse
                netdisco.conf for the database user and password. Run
                "sql/pg --help" for more options.

            Database Upgrades
                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 "sql/pg_dump" 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.

                You will have to run the following command to add new tables
                and modify existing ones.

                 cd /usr/local/netdisco/sql
                 ./pg upgrade-0.94-to-0.95.sql

                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 "upgrade-0.93-to-0.94.sql" first.

            Security Warning
                WARNING! 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.

                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 "Security Warning" in README for more
                information.

        v0.93 -> 0.94

            Autodetection of Uplink Ports
                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.

                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.

            SNMP::Info
                You will need SNMP::Info v0.9 in order to support the new
                netdisco-mibs package.

            Database Upgrades
                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.

                You will have to run the following command to add new tables
                and modify existing ones.

                 cd /usr/local/netdisco/sql
                 ./pg_run upgrade-0.93-to-0.94.sql

                Note that it is safe to run the upgrade.sql scripts more
                than once (in case you are running a CVS or RC version).

            GraphViz

                Program
                    Make sure you have a relatively new version. If you get
                    an error similar to

                      Creating CMAP : /usr/local/netdisco/html/netmap.map
                        warning, language cmap not recognized, use one of: ps hpgl pcl mif...

                    You need a newer version of GraphViz

                GraphViz.pm 2.01
                    The newest Perl interface to GraphViz (non-dependent on
                    the GraphViz release) has some better client map
                    interfaces for the Network Graph.

                    Please make sure this newest version is installed.

                     perl -MCPAN -e shell
                        install GraphViz

                    Double check the version.

                     perl -MGraphViz -e 'print $GraphViz::VERSION'

            Perl Modules
                A lot of the Perl modules that Netdisco depends on have
                released newer (better) versions. Go to the INSTALL and
                follow Part 8.1 "Perl Modules and Mason". If you use CPAN,
                it will upgrade all the dependency modules for you too.

            Bay Switches
                If you have bay switches, note that the naming scheme for
                the ports has changed from 1 to 1.1 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.

        v0.92 -> 0.93

            GraphViz 0.10
                You may want to install this latest version of GraphViz

            Database Upgrades
                For some of the new features, fields have been added to some
                of the database tables. A .sql file has been made to make
                the changes for you. Please run :

                 cd /usr/local/netdisco/sql
                 ./pg_run upgrade-0.92-to-0.93.sql

                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? ("sql/pg_back")

            New MIB Files
                If you insist on using this old version of netdisco, at
                least download the "netdisco-mibs" package and use that.

        v0.91 -> 0.92
            Make sure you run "Database Cleanup" or "-K" 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.

        v0.90 -> 0.91

            netdisco_apache.conf
                Double check that your copy of netdisco_apache.conf has the
                settings right for all the "session_*" directives.

            GraphViz
                Make sure you have GraphViz 0.9 installed.

APPLICATION NOTES

  Apache / Mod_perl

    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.

  SNMP::Info

    When upgrading to any version, please make sure you have the newest
    version of SNMP::Info installed (at least 2.04):

    CVS Version
        To update a CVS version of SNMP::Info :

            cd /usr/local/netdisco/SNMP
            cvs update

    CPAN Version
        To update a version installed by CPAN :

            perl -MCPAN -e shell
            install SNMP::Info

    Manual Install Version
        Download the newest version from CPAN or
        <http://snmp-info.sourceforge.net> and install.

General Upgrade Procedures

    Read INSTALL
        Read the INSTALL file that comes with the new version to see what
        has changed. Make sure you have all the Requirements listed.

    Backup Database
        For any version you will want to make backup copies of all your data
        first.

            cd /usr/local/netdisco/sql
            ./pg --back
            scp db_back*.gz somesafehost:

    Backup Configuration Files
        Make backups of all your files.

            tar cvf - -C /usr/local netdisco | gzip > 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

    Vacuum full and reindex database
        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.

        This will REINDEX and VACUUM FULL your database.

        On a recent Postgres 7.3 install this changed the database size from
        16GB to 400 MB! Sound worth it?

    Install on top of existing Netdisco
        Put the new files in your netdisco/ directory

            cp -R /path/to/netdisco-new-0.999 /usr/local/netdisco

    [Optional] Upgrade Perl Modules
        Following the procedures in INSTALL, now would be a good time to
        upgrade all the required Perl modules.

        This step is optional, unless a certain Perl module is listed for
        your version.

    Check Permissions
        Make sure the permissions are set to let the web user read the html/
        directory and write to the mason/ directory.

    Modify the Configuration Files
        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.

    Restart Apache
        You must do a full restart on apache (not a "graceful" or "restart")
        so that Netdisco will use the newly installed version of
        netdisco.pm.

            /usr/local/apache/bin/apachectl stop
            /usr/local/apache/bin/apachectl start

    Restart Admin Daemon
        You need to restart the admin daemon to run on the new copy of
        Netdisco.

            su - netdisco -c "/usr/local/netdisco -p restart"

    Reload Crontab
        Review netdisco.crontab and reload it for the "netdisco" user.

            su 
            crontab -u netdisco /usr/local/netdisco/netdisco.crontab