1v2.15 How to Install routers.cgi script 2 --------------------------------- 3 4Before Starting 5--------------- 6First, you need to make sure you have the following installed: 7 MRTG 8 RRDTool (v1.0.39 or later). Install perl modules under site-perl. 9 Perl (V5 or better). If under NT, make sure you have configured any 10 necessary extension associations and so on. 11 Perl CGI libraries (many installs, eg ActivePerl, have this as standard) 12 Perl File::Basename library (this is probably standard) 13 Perl Text::ParseWords library (this is probably standard) 14 Perl Net::SNMP library (only if you want to use Routing Table extensions) 15 Perl GD library (if you want to use the compact summary screen) with 16 the necessary gd support libraries ( see http://www.boutell.com/gd/ ) 17 Perl Time::Zone library (not required, but used if you have it. If 18 using multiple timezones under Windows then you really need it) 19 A web server (duh). If using Apache, you need mod_expires 20 21You probably already have most of these, if you have already installed MRTG 22and RRDTool. 23 24Before using mod_perl or speedycgi, check out the sections in the PROBLEMS 25and HOWTO documentation! 26 27Make sure you have the latest version of routers.cgi. Check on 28http://www.steveshipway.org/software/ 29 30Next, you need to make sure of the following: 31 32* All MRTG .conf files to be handled by routers.cgi have the 'UseRRDTool' or 33 'Logformat: rrdtool' option set, and their databases are in RRDTool format. 34* Each MRTG .conf file deals with a different router. (Not necessary, but 35 advised) 36 37The last will be correct if you created your .conf files using the 38cfgmaker command that comes with MRTG. I suggest you use the cfgmaker 39command with the '--descint --ifdesc=descr' options set. 40 41Fast Install 42------------ 43If you have a faily generic system, running NT or some flavour of UNIX, 44probably with either IIS or Apache, then you can use the install script. 45In fact, unless you have a very unusual setup, you can probably use this 46script. 47Just run: 48 perl install.pl 49and this should ask you a few questions, giving sensible defaults most of the 50time. Unless you have a customised system, this should install it for you! 51 52If you cannot use install.pl, or you prefer to do it by hand, then read on. 53 54If you have not yet created your MRTG .cfg files, you may wish to use the 55script buildwan.pl in the extras directory -- it creates all necessary .cfg 56files for your entire WAN. 57 58Also, see the section at the bottom about running targetnames.pl 59 60Use of routers.cgi under Windows NT 61----------------------------------- 62I have now tested this with Apache and ActivePerl. However, there are a few 63caveats. The script relies on the .htaccess file to force the expiry of 64old graphs. If you are using Apache under NT this is still OK, but IIS 65does not use the htaccess file. You need to ensure that the graphs directory 66is either set for the appropriate expiry times, or set to NEVER CACHE. 67After taking a look, it appears that in IIS you can only set expiry times for 68an entire directory at once. So, set the graphs directory to expire in 695 MINUTES. 70 71Installing routers2.cgi (not using install.pl) 72---------------------------------------------- 73 74You will need to modify the '#!/usr/local/bin/perl' on the first line of the 75scripts to reflect the correct location of your perl executable (the install 76script does this for you). 77 78Dont forget to install the RRDs perl libraries! 79 80Remember that while NT uses backstrokes '\' as path separators, URLs use 81forward strokes '/'. So, when editing the routers2.conf file, make sure you 82use the correct strokes when defining URL paths and filename paths. 83 84People using ActivePerl should look in the documentation to find out how to 85set up their web server to run Perl CGI scripts. This can be found at: 86http://velocity.activestate.com/docs/ActivePerl/faq/Windows/ActivePerl-Winfaq6.html 87 88Most of these instructions are UNIX-centric. Windows NT people should make the 89appropriate changes for directory paths, permissions, and so on. You will 90obviously need the Windows version of Perl installed and made CGI-able. The 91same applies to people with Macs or any other more obscure OS. 92 93Timezone support under Windows is minimal, due to limitations of the O/S that 94are compiled into RRDTool. Under windows, you cannot have a different 95timezone for each target. If this is a problem, then stick with MRTG (the 96compiler used for MRTG does not have the problems that RRDTool does). This 97may well be corrected in a later version of RRDTool - so get the latest version! 98 99Creating Directories 100-------------------- 101Now you need to decide where to put the files. The directories you will 102need are as follows: 103 104CGI-BIN DIRECTORY: This is where the routers.cgi file goes, with read and 105 execute permission. This directory should be visible to your web browser 106 with exec-cgi flag set. ( 'Script' flag in IIS ) 107 108ICONS DIRECTORY: This is where all the .gif files are put. This directory 109 should be visible to your web browser. Make a note of the directory's URL 110 This should not be under the CGI-BIN directory. Usually called /rrdicons 111 or similar. 112 113GRAPHS DIRECTORY: This is the work directory for the graphs. It needs to 114 be writeable to the httpd UID, and otherwise empty. The htaccess file should 115 be placed in here. This directory also needs to be visible to your web 116 browser. Make a note of the URL of the directory, and its path in the 117 filesystem. Note that under some web servers you do not have the htaccess 118 file - you should do whatever is equivalent on your server. Also, Apache 119 needs to have the mod_expires module installed to use htaccess. IIS users 120 should set the directory to expire in 5 MINUTES. 121 This should not be under the CGI-BIN directory. 122 123DATABASE DIRECTORY: Where the RRDTool .rrd databases are kept. This should 124 already exist. It should not be under your web server root. 125 126MRTG CONF DIRECTORY: Where the MRTG .conf files are kept. This should 127 already exist. It should not be under your web server root. 128 129Configuring the perl script 130--------------------------- 131This is now done via a separate configuration file. You should modify the 132script so that it knows where the conf file is (the line is clearly marked 133at the beginning of the .pl file), and (if necessary) modify the path of 134the perl executable in the first line of the script. ( $CONFFILE = "...." ) 135 136The conf file should have at least 2 sections, [web] and [routers.cgi]. The 137first needs an entry 'backurl' to define where the 'Main Menu' button takes us. 138The other section defines all the other options that used to be hardcoded into 139the script. 140 141A third section, [routerdesc], is now DEPRECATED. Don't use it unless you 142have to. 143 144A fourth section, [targetnames] is optional and allows you to override the 145default short description for the routers and interfaces. You key this 146section with either the MRTG .conf file name, or the interface target name. 147 148The short description for a router is taken as: 149 : The entry for the MRTG .conf file in the [targetnames] section 150 : The entry in the [routerdesc] section, or 151 : The 'ShortDesc[_]: ....' entry in the mrtg.conf files, or 152 : The first word in the 'Title[..]: ...' line in the mrtg.conf files 153 (this is also the key used to uniquely identify the router in 154 the [routerdesc] section) 155 156A fifth section, [targettitles] is optional and allows you to give the 'long' 157description for each interface. This corresponds directly to the Title[] 158directive in the MRTG files. If you made your MRTG config files using 159cfgmaker with the --descint option, you may not need do do anything here. 160 161See the example routers2.conf file, and the README file for more information. 162 163You now need to put this configuration file somewhere - I suggest in 164/usr/local/etc - and then modify the script routers.cgi so that it knows 165where to find this file. The line to modify is clearly indicated at the 166start of the script. As shipped, it is configured to be kept in the file 167/usr/local/etc/webdev.conf 168 169targetnames.pl 170-------------- 171This is a script to automatically build the [targetnames] section of your 172routers2.conf. AFTER configuring the routers2.conf file, you can run this 173using the command 174 perl targetnames.pl routers2.conf > targetnames.conf 175changing 'routers2.conf' to be the full pathname of wherever you have installed 176your routers2.conf file. If you used the install.pl script, this will probably 177be in the same directory as your .rrd files. 178This command will use SNMP to query your routers, and will output on STDOUT 179into targetnames.conf the necessary configuration directives which you can edit 180and add in to your routers2.conf file. 181The script looks in SNMP for the interface names and descriptions (if they are 182available) and formats them for the routers2.conf file. 183 184Installing the files 185-------------------- 186Copy the routers.cgi file to the CGI-BIN directory, permission 555 (read 187and execute). If it is called routers.cgi.pl in the package then rename 188it to routers.cgi (UNIX, Apache) or routers.pl (NT with IIS) 189 190Copy the htaccess file to the GRAPHS directory as .htaccess, permission 444. 191This is not necessary if your web server does not use htaccess files - you 192should do the equivalent for your server. Apache may need mod_expires 193activated for htaccess to work, and AllowOverride set for the GRAPHS directory. 194 195Copy the *.gif files to the ICONS directory. 196 197Testing the script 198------------------ 199It should now work! Point your browser at the routers.cgi file, and see 200what you get. Note that you MUST have javascript enabled on your browser 201for the pages to function correctly, and you need cookies enabled if you 202want to use the personal preferences page. 203 204routingtables.cgi 205----------------- 206You may wish to use the experimental Routing Tables extension. To use this, 207you must do the following: 208* Install Net::SNMP 209* Install the routingtables.cgi script in your CGI bin. 210* Uncomment the 'routingtableurl' directive in the routers2.conf 211This will result in a new link appearing on the 'info' page for each router, 212allowing you to view the current routing table on the router in question. 213Note that this may have problems with NT servers, particularly when used with 214IIS as the web server. 215The link will be hidden in the event that it cannot work out the necessary 216information. 217Also, your community strings will appear in your browser history. If this is 218a security concern to you, then do not enable this feature. If you do enable 219it, then make sure your community strings are READ ONLY and preferably 220restricted to just the IP address of this monitoring server. 221 222Contacting me 223------------- 224Try one of the following: 225web: http://www.steveshipway.org/software (main site) 226 http://www.shipway.org.uk/software (popup ads - yeuchk) 227email: steve@steveshipway.org (preferred), s.shipway@auckland.ac.nz (work), 228 steve@shipway.org.uk (last chance) 229mailing list: http://www.steveshipway.org/mailman/listinfo/support_steveshipway.org 230forum: http://www.steveshipway.org/forum/index.php 231Yahoo IM: steveshipway 232ICQ: #210588157 233AIM: shipwaysteve 234MSN: s.shipway@auckland.ac.nz 235Please don't telephone me, unless you want to offer me money :-) 236 237Thanking me 238----------- 239Encourage development by sending me something from my Amazon Wishlist 240http://www.amazon.co.uk/exec/obidos/registry/3S0PX0NTU8KDC 241Details on http://www.steveshipway.org/software/wishlist.html 242 243People who send me something have their names added to the Information page, 244and also get a warm, fuzzy feeling deep within from having given something 245back... 246 247-Steve 248