userapps/opensource/net-snmp/perl/manager/INSTALL

   1 REQUIREMENTS
   2
   3   A knowledgeable user.  This system is *not* entirely user friendly
   4   yet.   You have been warned.  Use at your own risk.  yada yada yada.
   5
   6   Get and install:
   7
   8     the mysql (http://www.mysql.com) database
   9       it may work with other databases, but I haven't tried.
  10
  11     Apache (http://www.apache.org)
  12
  13     The following perl modules (http://www.cpan.org):
  14       mod_perl
  15       SNMP (from the net-snmp source tree: SRCTREE/perl/SNMP)
  16       CGI
  17       DBI
  18       DBD::mSQL
  19       GD::Graph
  20
  21     You may need more modules depending on your perl version, so sorry
  22     in advance if I missed some.
  23
  24   Building and setting up mysql (a summary of what is needed.  See the
  25   mysql documentation for further details):
  26      ./configure
  27      make
  28      make install
  29      scripts/mysql_install_db
  30
  31      start it by running 'safe_mysqld'.
  32      To run the sql commands listed in the following text, run
  33      'mysql'.
  34
  35 SQL REQUIREMENTS
  36
  37   The scripts used by this project automatically create, edit, delete,
  38   insert, update, etc everything necessary.  Because of this, you'll
  39   need to set up a SQL user with the ability to modify the heck out of
  40   a database called "snmp" on your mysql server.  We'll call this user
  41   SQLUSER below, and its password SQLPASSWORD.  Replace these with
  42   your appropriate information anytime you see them listed below.
  43
  44 INSTALLING THE PERL MODULES
  45
  46   perl Makefile.PL
  47   make
  48   make install
  49
  50   Copy the red.gif, and green.gif graphics files to your apache
  51   HTML-ROOT/graphics/.
  52
  53 SETTING UP APACHE
  54
  55   (assumes you have mod_perl installed properly from above)
  56
  57   Idealy, it should be put behind a user/password database in your web
  58   server (something that sets the REMOTE_USER environmental for CGI
  59   scripts).  This will greatly enhance its operation so that different
  60   users can be users of different groups of hosts, etc...  If this is
  61   not done, everyone will use the user name "guest".
  62
  63   At the bottom of your httpd.conf file or in an apporpriate
  64   VirtualHost directive put the following lines, appropriately
  65   configuring the sql username, etc.  I strongly recommend turning on
  66   SSL support for this as well.:
  67
  68     PerlModule netsnmp::manager
  69     <Location /manage>
  70          # put apache protection stuff here, like a password database etc!!!
  71          SetHandler perl-script
  72          PerlHandler ucdsnmp::manager
  73          PerlSetVar hostname SQLHOST
  74          PerlSetVar dbname snmp
  75          PerlSetVar user SQLUSER
  76          PerlSetVar pass SQLPASSWORD
  77
  78          # turn on password protection.  see apache htpasswd documentation.
  79          # comment these out for unauthenticated access (generally a bad idea)
  80          AuthType Basic
  81          AuthName "SNMP manager access"
  82          AuthUserFile /etc/httpd/conf/manager-passwd
  83          require valid-user
  84
  85     </Location>
  86
  87    Restart apache after you've done the above.
  88
  89 SETTING UP THE MYSQL UCD-SNMP DATABASES
  90
  91   Use the following perl script to set up the mysql database tables
  92   required:
  93
  94     ./setupdb -u SQLUSER -p SQLPASSWORD -h SQLHOST
  95
  96   To display what this will do before you run it:
  97
  98     ./setupdb -v -n
  99
 100 SETTING UP USERS OF THE SYSTEM
 101
 102   Now you need to add yourself as a user.  You'll want to use a
 103   username that you configured for your apache password file (or
 104   whatever), or the user "guest" if you didn't configure apache for
 105   authenticated access.  The -a in this case grants "administrative"
 106   rights to the group of hosts, and thus allows the user to add new
 107   hosts to the group, delete hosts, etc.  Non-administrative users are
 108   mostly "read-only" type users.
 109
 110   The interface groups hosts together in "groups", and you put users
 111   in these groups to assign responsiblity for them.  Groups are
 112   created when a user gets assigned to one, so just pick a groupname
 113   for now and use it below.  Maybe later you can add yourself to a new
 114   group using a similar command, and the web interface will change to
 115   reflect that you are now in more than one group.  Use the same group
 116   name for multiple users that all belong to a single "group".
 117
 118   If you add an email address to the argument list the system will
 119   mail that user every time it finds a problem or finds a problem that
 120   has been fixed.
 121
 122   *** DO NOT PICK A GROUP WITH THE NAME "default" ***
 123
 124     ./setupuser -u SQLUSER -p SQLPASSWORD -h SQLHOST -a GROUPNAME USERNAME [EMAILADDRESS]
 125
 126 SETTING UP SNMP AUTHORIZATION INFORMATION
 127
 128   Now, you need to add in your default authorization information for
 129   how to make SNMP requests to your host.  The parameter names you can
 130   pick come straight from the SNMP perl module, so see "perldoc SNMP"
 131   for all the parameter names you can pick from.
 132
 133   Examples:
 134
 135     ./setupauth -u SQLUSER -p SQLPASSWORD -h SQLHOST Version 1 Community public
 136     ./setupauth -u SQLUSER -p SQLPASSWORD -h SQLHOST Version 3 SecName 'v3user' AuthPass 'myv3passphrase' SecLevel authNoPriv
 137
 138   I also recommend adding a large default timeout (30 secs):
 139
 140     ./setupauth -u SQLUSER -p SQLPASSWORD -h SQLHOST Timeout 30000000
 141
 142   If you want different parameters for a group, it'll inherit
 143   everything from the default parameters specified above plus any more
 144   that you set or override:
 145
 146     ./setupauth -u SQLUSER -p SQLPASSWORD -h SQLHOST -g agroup Community private
 147
 148   Further, hosts can be given specific parameters as well if they're
 149   really special:
 150
 151     ./setupauth -u SQLUSER -p SQLPASSWORD -h SQLHOST -m host Timeout 60000000
 152
 153 COLLECTING THE DATA
 154
 155   The command you need to run to collect data is snmptosql, which will
 156   use the information defined above to fill your data base with all
 157   sorts of useful information that you've asked it to collect.
 158   Something like:
 159
 160     snmptosql -H SQLHOST -u SQLUSER -p SQLPASSWORD
 161
 162   should be put in cron to update a regular intervals.  I run mine
 163   every 10 minutes.  Note that it will *not* scale to a large number
 164   of hosts easily at the moment.  Start with no more than 20 or so to
 165   begin with.
 166
 167 USING THE SYSTEM
 168
 169   Most of the things you'll need to do can be done from the web
 170   interface that you've just set up as /manager on some system in the
 171   step above.  Go to this web page to see what you can do.
 172
 173 MONITORING HOSTS WITH IT (finally)
 174
 175   It's *not* entirely intuitive yet.  So, lets give you an example.  In
 176   your snmpd.conf file, put a line that says "proc sendmail".  This will
 177   check to see if sendmail is running on your system.  Also put "disk /
 178   10%" which will require the disk has at least 10% of free space.
 179   Restart the snmpd (or kill -HUP).  See the snmpd.conf manual page
 180   for some details.
 181
 182   Then, go to the above URL and click on the group name you want to
 183   add a host to and enter the host name in the dialog box near the
 184   bottom of the page (assuming you're logged in as an administrator
 185   user setup using the -a flag to setupuser above).  Click on the
 186   "setup group XXX" link at the bottom of the group's page and click
 187   on all the check buttons (you can turn them all on even if you're
 188   not really using them all) and hit the submit button.
 189
 190   Come back 10 minutes later, reload the group and click on the host
 191   name.  You should see pretty red/green lights if there is or isn't a
 192   problem.  It'll show you a few tables with the various bits of data
 193   it collected (including how many sendmail processes are running, an
 194   how much disk space is actually being used), etc.
 195
 196 GRAPHING
 197
 198   To be written.