HOWTO file v2.13 Howto file ---------- This file details how to perform configuration changes you might wish to do. Note that, due to changes since v1.x, this file often says 'Routers' instead of 'Devices', and 'Interfaces' instead of 'Targets'. ------------------------------------------------------------------------------ Q. How do I change the Router Names in the left-hand menu? A. Use the [targetnames] section in the routers2.conf file. Put in entries keyed by the MRTG .cfg filename, and these will replace the defaults. You can also change the defaults by changing the 'rtrdefault' setting in the routers2.conf - sometimes 'ai' works better. ------------------------------------------------------------------------------ Q. How do I group the routers by type in the Routers menu? A. You need to enable Grouping in the routers2.conf, by using the 'group = yes' option. Then, split the MRTG .cfg files into different directories, and add these to the 'cfgfiles' directive. Finally, use the [targetnames] section to define group names, keyed on the (full) path name of the files. eg, if the files are in /mrtg/config/a/*.cfg and /mrtg/config/b/*.cfg, then you should make the following settings: [routers.cgi] confpath = /mrtg/config cfgfiles = a/*.cfg b/*.cfg group = yes [targetnames] /mrtg/config/a = Group A /mrtg/config/b = Group B Note that if you move your MRTG .cfg files like this, you must make sure that your data gathering script still calls them! Also, people using generic.cgi to view the same files will need to upgrade to v0.13 or later. Why do we have both a cfgfiles and confpath defined? Historical reasons. People who still want to call the files via a single MRTG instance should use an 'Include' files over the top. ------------------------------------------------------------------------------ Q. How do I group the interfaces within a router? A. You can't - this is what the 'routers' menu is for. If you split your MRTG .cfg file into two parts, then it will appear as two 'routers' on the menu. You can use this to group the interfaces. However, since the interfaces are sorted by description, you could prefix the various names with a group code, which would affect the ordering. Use the [targetnames] section of the routers2.conf to do this. ------------------------------------------------------------------------------ Q. How do I hide all those PDA entries from the 'Style' menu? A. You have to modify the 'sorder' option in the routers2.conf. Be very careful doing this! Each entry corresponds to a particular style, so you can hide the ones you dont want. ------------------------------------------------------------------------------ Q. How do I change the titles that appear in the graphs? A. Depending on the size of the graph, the title will be either the interface Long or Short description, taken from the [targetdesc] and [targetnames] sections of the routers2.conf. If you have not defined anything here, then the 'Title[]' directive from the MRTG .cfg file will be used for the long description, and the short description will be worked out from the interface information. ------------------------------------------------------------------------------ Q. How do I re-scale the graphs, so that they do not always scale relative to the red 'max' line? I want them to auto-scale to the actual data. A. Put the directive: routers.cgi*Options[target]: scaled in your MRTG .cfg file for the targets you wish to autoscale. A. Alternatively, use the 'unscaled = no' option in the routers2.conf (which affects ALL graphs), and optionally put the directive Unscaled[target]: dwmy in the MRTG .cfg files, for the target(s) that you want to remain unscaled. Note that MRTG defaults to scaled, whereas routers.cgi defaults to unscaled (unless you change this using the 'unscaled = no' directive). ------------------------------------------------------------------------------ Q. How do I make the router CPU statistics appear as well? A. You have to add a new target to your router's MRTG .cfg file for the CPU statistics. This will be different depending on your type of router. The target name MUST contain 'CPU' to indicate to the script that this is the CPU target. For example, if you have a Cisco router, you should use something similar to the following: Target[routername-CPU]: 1.3.6.1.4.1.9.2.1.58.0&1.3.6.1.4.1.9.2.1.58.0:communityname@routername Title[routername-CPU]: CPU Percentage for routername MaxBytes[routername-CPU]: 100 Options[routername-CPU]: integer gauge noo PageTop[routername-CPU]: dummy Note the following: 1) You MUST have the 'CPU' in the targetname - this is how routers.cgi identifies which target is the CPU statistics. 2) You MUST have a MaxBytes of 100. routers.cgi uses this as an additional test to verify that it has the correct target. 3) You will almost certainly have to have 'Options[...]: gauge integer' 4) The OID used in the example Target line is the Cisco 5-minute CPU load average. Other manufacturers will have a different OID. 5) Only the first OID is used, so, make them both the same. ------------------------------------------------------------------------------ Q. How do I enable the routingtables.cgi extension? A. Be aware of the security implications. Then, do the following: * Install Net::SNMP * Install the routingtables.cgi script in your CGI bin. * Uncomment the 'routingtablesurl' directive in the routers2.conf This will result in a new link appearing on the 'info' page for each router, allowing you to view the current routing table on the router in question. Note that this may have problems with NT servers, particularly when used with IIS as the web server. The link will be hidden in the event that it cannot work out the necessary information. Also, your community strings will appear in your browser history. If this is a security concern to you, then do not enable this feature. ------------------------------------------------------------------------------ Q. How do I specify a URL that will only show the graph frame, not the header or menu frames? A. Put '&page=graph&nomenu=y' at the end of the generated URL. ------------------------------------------------------------------------------ Q. How do I see the configuration verification pages? A. Call the script with the 'page=verify' option, eg, http://yourserver/cgi-bin/routers.cgi?page=verify ------------------------------------------------------------------------------ Q. How do I change the behaviour of downloaded CSV data? A. This is mostly down to the configuration of your browser and operating system. However, you can set the options 'csvmimetype' and 'csvfilename' in the [web] section of the routers2.conf to help tune this, if the defaults are not to your liking. IE/Windows people will need to set the 'csvfilename' to a filename with the appropriate extension for a CSV file in your configuration. You should then set O/S defaults within File Manager (Windows Explorer) to associate this extension with the appropriate application. Everyone else should tell their web browser to associate the 'csvmimetype' with the appropriate behaviour. Note that in Internet Explorer, filename extension takes priority over MIME type, unlike in the rest of the world. ------------------------------------------------------------------------------ Q. How do I suppress the devices/targets menus, while still allowing the user to select display options? A. You can put the 'allowexplore = no' option in the [routers.cgi] section of the routers2.conf to do this. It will suppress the 'Devices' and 'Targets' menus in the lefthand frame. If you put 'allowexplore = if' then it will only suppress the Devices menu, not the targets. ------------------------------------------------------------------------------ Q. How do I get averages over a working day, rather than the full 24hrs? A. You can set the 'daystart' and 'dayend' hours in the routers2.conf, and the graphs will show the working day averages in addition to the normal data. Note that Saturday and Sunday are defined as the weekend - currently this cannot be changed (sorry, Israel and the Arab nations). Work hours are only done at an hourly granularity, due to the RRD granularity, so you cannot have a working day that ends at 5:30pm, for example. ------------------------------------------------------------------------------ Q. How do I change the icon appearing next to the items in the Targets or Devices menus? A. You can specicy a file name for a 15x15 pixel GIF image by adding a line of the form routers.cgi*Icon[targetname]: icon.gif to your MRTG .cfg file. The icon.gif file must live in the iconpath directory defined in your routers2.conf file. It can be given any name. Use the correct targetname as well! A. You can also specify an Interface icon using the [targeticons] section of your routers2.conf file. This will override any icon defined in the MRTG file. To do this, place a line of the form: targetname = icon.gif in the [targeticons] section of routers2.conf, using the appropriate targetname. A. For devices, you can place a single directive in each MRTG file of the form: routers.cgi*Icon: icon.gif This will set the icon on the Devices menu for that file. A. Similarly, you can make an entry in the [targeticons] section of your routers2.conf, keyed on the MRTG file name: mrtgfilename.cfg = icon.gif A. Finally, you can set the default icon to use (in cases where the AI code is unsure what to do) by using the routers2.conf directives filedefault and ifdefault. ------------------------------------------------------------------------------ Q. I have some interface data that is being classified as a 'non-interface' target. How can I specify it as an interface? A. You can add some lines to your MRTG .cfg file as follows: routers.cgi*Options[targetname]: interface Options[targetname]: bits YLegend[targetname]: traffic in bits/sec Legend1[targetname]: Incoming traffic Legend2[targetname]: Outgoing traffic Remember to use the correct targetname! The first line tells routers.cgi that it is to be treated as an interface. The other four are needed because routers.cgi will not set these defaults for you if it is not sure. ------------------------------------------------------------------------------ Q. How can I have separate MRTG .cfg files (which is how routers.cgi wants them to be), and yet still have only a single instance of MRTG running for the RRD update cycle? Q. What is the recommended way to set up my MRTG .cfg files for the routers? A. The recommended way of defining your MRTG .cfg files is to have one file per router. This will allow routers.cgi to group the interfaces by router in the menus. What you should then do is to create a special .cfg file, which should contain nothing but Include: directives, including all of the other .cfg files. You then pass this special .cfg file to MRTG as the file to update. MRTG will only have a single instance, but routers.cgi will still be able to work with multiple router configuration files. This 'master' .cfg file should also contain the directive routers.cgi*Ignore: yes so that routers.cgi does not put it into the menu. ------------------------------------------------------------------------------ Q. How do I enable to support for 6-hour graphs for a given router? A. This requires three steps. 1. Add the directive '6hour = yes' to the [routers.cgi] section of your routers2.conf file to enable the support in routers.cgi 2. Add the MRTG directive 'Interval: 1' to the appropriate MRTG .cfg file(s) to enable creation of the higher-resolution .rrd file. You may need to delete your old .rrd file in order for it to be re-created with the new resolution. 3. Make sure you run MRTG every minute (instead of every 5 mins) in order to collect the data. If you run it as a daemon you should be OK. After making these changes, you should be able to see the new '6 hour' graph option on the routers.cgi pages. ------------------------------------------------------------------------------ Q. How do I make the graphs show time relative to the timezone in which the routers are located? A. Firstly, note that this will probably not work if you are using Windows. It does work under Linux and Solaris, and probably all other UNIX systems. This is due to a limitation of the operating system's 'C' libraries, which are compiled into the RRDTool graphing functions. You should add the 'Timezone[]:' directive to your MRTG .cfg file for each target, specifying where the target is located. How you specify the timezone depends on your operating system - eg, 'GMT+2', 'PST', 'Singapore' and so on. This will cause the following: 1. The timezone will be reported at the bottom of the page, next to the 'last update' time. 2. The graph will be shown with time relative to the given timezone - if it is not, then your O/S does not support dynamic timezones. 3. The 'working day' (if you use it) will now be relative to the target's timezone, and not to the server's. ------------------------------------------------------------------------------ Q. How do I make different 'working day' hours for different routers? A. Currently, you can't. However, if your O/S supports dynamic timezones, you can place targets within different timezones. Then, the working day will be defined relative to the router's timezone, and not the server's. See the 'timezone' question for more information. ------------------------------------------------------------------------------ Q. How do I change the icon graphcs to something more readable? A. Some alternative icon schemes are supplied in the altgif directory. Go into this directory, and choose one of the schemes. Copy the appropriate icon set (all the *.gif files) into your rrdicons directory, wherever you decided to put it. Then, flush the cache on your browser, and you should have the new set active! If you want to design your own set, then please send a copy to me so that I can put it on the website for anyone else to use. ------------------------------------------------------------------------------ Q. How do I stop an interface from being listed in the 'Interfaces' menu, or the 'Summary' page? A. Add the directive 'routers.cgi*InMenu[targetname]: no' to the appropriate MRTG .cfg file, for the appropriate target. This will suppress its listing in the Interfaces menu, however it will still appear in the Incoming and Outgoing (if is is an interface) and in the Summary pages. You can also use the 'routers.cgi*InSummary[targetname]: no' directive to prevent the target from being listed in the Summary pages. You can also use the 'routers.cgi*InOut[targetname]: no' directive to prevent the target from being listed in the Incoming/Outgoing pages. Finally, 'routers.cgi*Options[targetname]: ignore' will completely remove the target from any menu, summary or screen. ------------------------------------------------------------------------------ Q. How do I change the Interface names appearing in the left-hand menu? A. There are several ways to do this. In order of precedence, these are: 1. Set an entry in the [targetnames] section of the routers2.conf targetname = Shortdesc 2. Set the MRTG_INT_DESCR option in the MRTG .cfg file SetEnv[targetname]: MRTG_INT_DESCR="Shortdesc" 3. Change the default behaviour, by using the ifdefault option in the routers2.conf file. Set to 'target' to make the targetname the default. ifdefault = target ------------------------------------------------------------------------------ Q. How do I prevent a particular target from being processed by routers.cgi? A. If you want to ignore just some of the targets in a .cfg file, then add the directive: routers.cgi*Options[targetname]: ignore to the MRTG .cfg file. This will result in the target being completely ignored. ------------------------------------------------------------------------------ Q. How do I get the GD libraries installed? A. If you are using ActiveState Perl for Windows, use the 'ppm' command to download the GD package. This installs it automatically. Easy! C:> ppm install GD Note that, if you use a proxy server for Internet access, you will need to set the proxy environment variables as detailed in the ppm documentation. eg: set HTTP_proxy=http://proxy:8080 set HTTP_proxy_user=john set HTTP_proxy_pass=secret See http://aspn.activestate.com/ASPN/PPM/FAQ for full instructions. A. If using UNIX, then the GD C library is already installed by your rrdtool install - although maybe not in the /usr/lib directory. Download the GD perl package from www.CPAN.org, and follow their installation instructions. Make sure that your libgd.a is of recent enough version for your GD.pm perl libraries! You may need to download it again from www.boutell.com If you get the yellow 'error' graphic, then GD.pm is not installed fully, or the dynamic libraries are incorrect. If you get nothing but a grey bar graphic, then your libgd.a C library is too old - get a more recent version and then reinstall GD.pm perl library. ------------------------------------------------------------------------------ Q. How do I install the Net::SNMP libraries? A. If using Active Perl, use the PPM command to download: C:> ppm install Net::SNMP Note that, if you use a proxy server for Internet access, you will need to set the proxy environment variables as detailed in the ppm documentation. See http://aspn.activestate.com/ASPN/PPM/FAQ for full instructions. A. If using UNIX, download the package from http://www.cpan.org/ and follow the instructions contained within. ------------------------------------------------------------------------------ Q. How do I stop styles from appearing in the menu? I don't need all of the PDA and WebTV related styles, just the basic ones. A. You can modify the 'sorder' directive in the routers2.conf. Be very careful though - you must use the correct style names. The letter 'b' in a style mean 'black and white' *unreliable* The letter 'p' means PDA mode - no javascript The '2' means double height The s,t,n,l,x are different widths and data widths. l2p : Web TV s, sbp, nbp, sp, np : Various PDAs x, x2 : For 1024x768 screens l, l2 : For 800x600 screens t : Half data width zoomed for 640x480 screens (stretch) n, n2 : For 640x480 screens A few examples: # all available styles sorder = s t n n2 l l2 x x2 sbp nbp sp np l2p # no PDA or WebTV styles sorder = t n n2 l l2 x x2 # Just small ones and WebTV sorder = t n n2 l l2 l2p ------------------------------------------------------------------------------ Q. How do I define a User Defined graph? A. First, pick a short unique target name for the graph (eg: 'graphtarget'). Next, add a line similar to the following to each MRTG target definition that you want in the graph: routers.cgi*Graph[targetname]: graphtarget noo total You can also put a number of different options after the target name - noo Dont use the Outgoing lines noi Dont use the Incoming lines total Add a total line to the graph average Add an average line to the graph nolegend Dont put a legend at the bottom of the graph You can add these options on any of the Graph lines, they will all be used. Now you can optionally define a new Short Name (for the lefthand menu), a Title (for the graph itself), and an Icon (for the menu and Info page). You do this by adding the appropriate entry in the routers2.conf, eg: [targettitles] graphtarget = Incoming Traffic [targetnames] graphtarget = Incoming [targeticons] graphtarget = incoming-sm.gif All other graph settings (legends, etc) are taken from the first target defined for the user graph. Finally, you can add any other graph-related options using directives specific to the graph name target with an underscore prefix... routers.cgi*Ylegend[_graphtarget]: Traffic in bps routers.cgi*InSummary[_graphtarget]: yes This way, you can redefine the 'Total' and 'Average' labels, using the routers.cgi*LabelTI[_graphtarget]: Total incoming directive and its siblings. ------------------------------------------------------------------------------ Q. How do I change the default target that is selected by the system? A. You can modify the 'defaultinterface' option in the routers2.conf. By default, the first target in the list will be used. However, you may wish instead to specify the first Interface, or the CPU statistics (if available). eg: [routers.cgi] defaultinterface = interface You can also change the sort order of the targets in the menu - by default, they are sorted alphabetically by description, AFTER being sorted by their mode. So, incoming/outgoing come first, then CPU, generic, Interfaces and memory, and finally user defined. You can set this to mode (default), desc or icon: [targetnames] ifsort = desc The default device is selected either by the user's personal preferences, or by the defaultrouter directive in the routers2.conf ------------------------------------------------------------------------------ Q. How do I make the graph units show in the legend? A. Use the 'legendunits = yes' directive in the routers2.conf file. ------------------------------------------------------------------------------ Q. How do I enable the 95th Percentile and Total options? A. You have to set the 'percentile = yes' option in the routers2.conf ------------------------------------------------------------------------------ Q. How do I give individual users personalised routers2.conf files? A. You can almost achieve this using the 'extra' parameter, or by changing the name of the script, or via a username that has already been authenticated by your web server. Using the 'extra' parameter: First, set up a new section in the routers2.conf for the user or group that you have. For example, call it 'xxxx'. Now put extra directives into this section to override the directives in the routers.cgi section. eg: [routers.cgi] confpath = /mrtg/normal cfgfiles = router-*.cfg iconpath = /www/html/rrdicons [extra-xxxx] confpath = /mrtg/special cfgfiles = *.cfg Now, when you call routers.cgi normally, you will use the [routers.cgi] section, as usual. However, if you use the parameter 'extra=xxxx', then the [extra-xxxx] section will override confpath and cfgfiles (although iconpath will remain unchanged). Eg: http://myserver/cgi-bin/routers.cgi?extra=xxxx Using the script name: You can achieve the same result by renaming the script - for example, if the new section was called 'test.cgi', then you could copy the routers.cgi script to 'test.cgi', and when run it would use the [test.cgi] section as an override to the [routers.cgi] section. Using the username: First, you must configure your web server to authenticate the user. This will set the username in the CGI parameters. Then, create a new section in the routers2.conf file called [user-USERNAME] (for the appropriate USERNAME, of course). For example, if the user is 'steve', then create [user-steve] and put any per-user settings in here. You can make as many override sections as you like, although they will only override the [routers.cgi] section, and you can only use one of each type at once. Also, they must not have the same name as any other existing sections, else they won't work correctly. Note that, if you are really crazy, you can use all three of these methods simultaneously. I wouldn't advise it, though. ------------------------------------------------------------------------------ Q. How do I automatically add an archive entry for a graph at a specific time? A1. There are limited command line options to routers.cgi you can use. Call a script using your favourite scheduler software to create the archive. First, use the 'bookmark' button to find out the required 'rtr', 'if', 'xgstyle' and 'xgtype' parameters for your graph. Remember the last two will default if not set. Call routers.cgi like this: perl routers2.cgi -A -D rtrparam -T ifparam -s xgstyleparam -t xgtypeparam eg, perl routers2.cgi -A -D file.cfg -T ezwf -t d This will generate an archive graph for the current time, regardless of the archive settings in the routers2.conf file. If you omit the -T option, then ALL MENU ITEMS for this device will be archived. MAKE SURE that you are running this as the same user as runs the web server! Otherwise, you may find that either it does not have rights to create the graph archives, or it cannot read the rrd files, or else it can create the files but they are unreadable or undeletable by the routers.cgi interface! A2. Use your favourite scheduler to run the routers.cgi script interactively, with the appropriate parameters. You can find the necessary parameters by using the 'bookmark' button when viewing the graph you want to archive. Then, in your scheduler, call the script like this: (UNIX) perl routers2.cgi 'rtr=routerparam&if=ifparam&page=archive' > /dev/null (Windows) perl routers2.pl "rtr=routerparam&if=ifparam&page=archive" > NUL Dont forget to replace routerparam and ifparam with the appropriate values. You could also add the xgtype and xgstyle parameters if you wish a specific graph type or style. This will archive the graph into the appropriate subdirectories, to be viewed by the routers.cgi frontend (provided archiving is enabled). ------------------------------------------------------------------------------ Q. How do I use the CGI Extension facility? Q. How do I add customised links to the generated pages? Q. How do I use a plugin? A. You can attach your own CGI scripts to either a Device (.cfg file), or a Target (MRTG Target name). You do this using the Extension keyword in the MRTG file. To attach a CGI script to a Device, put something like: routers.cgi*Extension: "Menu desc" /cgi-bin/myextension.cgi in your MRTG file. A new item for this will appear under the 'Targets' menu. For a per-target link, use: routers.cgi*Extension[target]: "Menu description" /cgi-bin/myextension.cgi instead. For this, a link will appear under the graph for this target. To link to another target/device within the routers.cgi frontend (eg, to the router interface at the other end of this WAN link, for example) then use the routers.cgi*Link[target]: "Menu description" cfgfile.cfg targetname and this will add a new link at the page bottom. Note that the cfgfile should be named after removing the confpath, so it may have one or more directory parts remaining. To have a new link appear in the Devices menu, use the [menu] section of the routers2.conf file. These URLs are called as they are specified, with no added parameters. In all other cases, the CGI is called with a number of extra parameters in addition to any already specified. These are only added IF KNOWN ALREADY. So, if making a per-Device extension, it helps to put the definition at the END of the .cfg file (so that information like hostname, community etc is already known). If you have the keyword 'noopts' added, then this prevents ANY extra parameters from being passed to the plugin. The CGI community string is only passed if the keyword 'insecure' is added to the end of the Extension definition, since this is a security risk and rarely required. You can also pass a numerical security level, which is compared to the level defined using 'level = ...' in the routers2.conf. If the defined level is the same or greater than the Extension level, then the Extension is enabled. CGI parameters: fi = MRTG file name (within confpath) ta = MRTG target name c = Community string (potential security risk: only enabled with 'insecure' keyword) h = host name (if known) ifno = interface number, if appropriate t = HTTP target page object name b = a URL that will take you back to the routers.cgi screen conf = The filename of the routers.cgi configuration file url = The URL of the routers.cgi script L = effective security level An example template for creating these scripts is available in the extras directory. ------------------------------------------------------------------------------ Q. How do I write a plugin Extension script? A. A plugin is a CGI script that is passed a number of parameters by the routers.cgi script, and then produces an HTML page. CGI parameters: fi = MRTG .cfg file name ta = MRTG target name c = Community string (potential security risk, only passed if Extension is defined using 'insecure' option) h = host name ifno = interface number, if appropriate t = HTTP target page object name b = a URL that will take you back to the routers.cgi screen conf = The filename of the routers2.conf configuration file url = The URL of the routers.cgi script L = effective security level Not all of these are necessarily passed by the calling link. The generated page should: be directed towards the frame specified in the 't' parameter refer to the routers2.conf and 'fi' parameters if necessary If you really want to be flash, you can add the following Javascript to the page's onLoad() event: { parent.menu.location = '?page=menu&rtr=&if=__none&xmtype=options#top'; } which will remove the selection on the previous selected interface. A template for creating plugin extensions is available in the extras directory. It takes care of all of this extra stuff for you. If you create plugins, then they are separate programs and therefore not necessarily covered by the GNU GPL that covers routers.cgi. So, you can give away routers2.cgi, but charge for your own personally-created extension scripts, should you so wish. The template in the extras directory is distributed Public Domain, so feel free to use it as the basis of any extension scripts you create. ------------------------------------------------------------------------------ Q. How do I use the 'extended time' options? A. In order to do this you need the option enabled in the routers2.conf file, and your .rrd files extended. If you have the latest MRTG, you can probably use the RRDRowCount[_]: 1000 option to set the generated RRAs to be larger (default size is ~600, if you have a default Interval). This however will only take effect when creating an .rrd file, so you'd have to delete all your old saved data. The other way is by using rrdresize, which preserves your old data. You should not do this unless you are sure you know what you are doing! Doing this could severely damage your MRTG log files! The 'rrdextend.pl' script in the extras directory will take a MRTG .cfg file, and will extend all the associated .rrd files to double length. After this has been done, you can enable the 'extendedtime' option in the routers2.conf file, and then use 'Yesterday' and 'Last week' time windows. Be aware of what the rrdextend utility does before you use it! Last warning - be sure you know what you are doing before you try this! The rrdextend utility simply automates running multiple repeats of the rrdtool resize command on the appropriate .rrd files. Enabling the extendedtime option can cause odd behaviour if you do not have correctly extended .rrd files. ------------------------------------------------------------------------------ Q. How can I stop people setting the preferences for other users? A. The personal preferences are set using cookies, on a per-browser basis. If you use a multiple-config browser (eg, IE or Netscape) then these cookies are stored on a per-user basis. Therefore, people can only set their own preferences, adn this does not affect the other users of the system. Note that if you use Authentication or personal parameters (see previous) then you can set the routers2.conf parameters on a per-user basis as well. ------------------------------------------------------------------------------ Q. How can I have the graph date and time added to the graph itself? A. Use the 'withdate = yes' optionin the routers2.conf. This will add a date/time stamp in the lower righthand corner of the graph showing when it was created. This timestamp is in the local short date format - if it is incorrect,modify the 'shortdateformat' directive in the routers2.conf to have the correct style for your locale. ------------------------------------------------------------------------------ Q. How can I give each of my customers their own page, automatically set up by the system? A. To do this, you have to combine several steps. Basically, they are as follows: 1. Write a small script that calls the MRTG 'cfgmaker' script on a daily or weekly basis. Your script should take a 'seed' file of router IPs, and generate the necessary .cfg files. You may need to modify the cfgmaker script to your preferences, or use the Include: directive. Of course you can skip this step, and generate the .cfg files manually if you prefer to. 2. Set up your web server to use authentication, and make sure that the routers2.cgi script is protected. Alternatively, use the built-in authentication with LDAP etc (see elsewhere). 3. Use the per-user configs (as detailed previously). For each client, set up a new section in the routers2.conf that overrides the confpath and cfgfiles directives, to give access ONLY to their own .cfg files. You also want the default cfgfiles directive to be invalid, so set it to 'none'. 4. Set up the script in the extras directory to clean up the graphs directory on a periodic basis. Example routers2.conf lines: [routers.cgi] confpath = /mrtg/conf cfgfiles = none group = no archive = no [user-usera] cfgfiles = usera/*.cfg [user-userb] cfgfiles = userb/*.cfg [user-adminuser] group = yes cfgfiles = */*.cfg archive = yes [targetnames] /mrtg/conf/usera = User A's routers /mrtg/conf/userb = User B's routers Of course, if each client has only one router, you could use the 'allowexplore = no' directive, and just give them the correct URL for their own router. This is a 'security by obscurity' method, though, although it removes the need for user authentication or special routers2.conf sections. ------------------------------------------------------------------------------ Q. How do I link to just the graph graphic, with no surrounding HTML at all? A. If you really want to do this, then you can create your own IMG tags that pull graphs from routers.cgi. First, identify the complete URL to link to. Using routers.cgi, display the desired graph, and click the Bookmark button. To the generated URL, add a suffix '&page=image'. Now, generate your own IMG tag similar to this: Graph of targetname Obviously, use the URL you generated in the earlier stage. Note that not all graphs are compatible with this -- summary, compact, multi-graph, some user defineds, and so on will not work. Also, do not use the width or height parameters in the IMG tag, since the graph dimensions are variable. If you get an 'Error' graphic, then you probably have passed incorrect parameters to the IMG tag, or are asking for an incompatible graph. ------------------------------------------------------------------------------ Q. How do I enable the server monitoring extensions? A. First of all, you can only monitor UNIX servers this way. I've been unable to write an agent for the Windows servers due to a kernel limitation. In order to enable it, you need to do three things. 1) Install the getstats module on each server to be monitored, and link it in to the inetd.conf file. The getstats script is in the extras directory, and contains instructions. 2) Set up the gather script to run every 5 minutes on your routers.cgi server. This script will contact all the monitored servers, and collect the data. Make sure you make the necessary changes to the gather script. This is also located in the extras directory. 3) Set up the new sections in the routers2.conf file. Examples are at the end of the sample file. [servers] servername = Server Description You can also set icons in a similar way. Now you should enable the Servers extension in the routers2.conf with the directive [routers.cgi] servers = yes And you will see a new group (if you are using Groups) for the servers. Data collected is CPU usage, user count, and paging. ------------------------------------------------------------------------------ Q. How do I configure routers.cgi to correctly display a range -- for example, a high and low Ping round trip time? A. You can use the 'routers.cgi*GraphStyle[]: range' directive. For example, say you use the mrtg-ping-probe utility to obtain a high and a low ping round trip time. You can set your MRTG optins as follows: Target[x]: `/usr/local/lib/mrtg-ping-probe -q x` routers.cgi*InCompact[x]: no MaxBytes[x]: 10000 Title[x]: ping times Options[x]: gauge nopercent YLegend[x]: milliseconds ShortLegend[x]: ms Legend1[x]: Round Trip Time range Legend2[x]: Round Trip Time range Legend3[x]: High Peak 5min RTT Legend4[x]: Low Peak 5min RTT LegendI[x]: High: LegendO[x]: Low : routers.cgi*Options[x]: nomax fixunit nototal routers.cgi*GraphStyle[x]: range See the EXAMPLES file for more details. ------------------------------------------------------------------------------ Q. How can I use the built-in authentication? A. First, decide whether you are going to use LDAP or a password file to hold the passwords. Then, configure the necessary lines in the [web] section of the routers2.conf file. Note that you will need the appropriate perl modules installed if you intend to use LDAP or LDAPS! You should decide if you want to force authentication, or make it optional (in order to view additional devices). Also, decide how quickly you want the authentication to expire. Edit the routers2.cgi file to set CHOCOLATE_CHIP to something random. This is the secret key used in cookie authentication, along with IP address and user name. You dont /have/ to do this, but it is more secure if you do. Set up the per-user sections to override the [routers.cgi] section and grant the users access to different cfgfiles. eg: [web] auth-required = optional auth-key = secretmessage auth-expire = +60min ldap-server = ldap.auckland.ac.nz ldap-context = ou=People,O=University,c=NZ [routers.cgi] cfgfiles = public/*.cfg [user-admin] cfgfiles = private/*.cfg public/*.cfg group = yes In this setup, anyone can view the public files without having to log in, but you must log in as 'admin' to see the private files. Authentication is done via the LDAP server, and expires after 1 hour of inactivity. ------------------------------------------------------------------------------ Q. How do I enable the rrd-archiving facility? A. First remember this can increase the size of your rrd directory by a factor of 40 in order to hold a month's detailed data! To enable, take the following steps: 1) Modify the rrd-archive.pl script to specify the correct location for your perl executable, and the routers2.conf file. 2) If you have an unusual routers.conf setup, then add the necessary [archive] section as in the example file 3) Use your scheduler to run the rrd-archive.pl script every night just before midnight (or alternatively every Sunday night at midnight if you only want weekly archives) 4) run the rrd-archive.pl script once manually (as the same user that runs the schedule and MRTG jobs!) Routers.cgi should now spot the existance of the archive directory, and you will get a new date option under the Graphs menu. You can tune the archiving on a per-target basis if you require. The date menu will only appear if archives exist for the current target. To do this, use the .cfg file directive routers.cgi*Archive[targetname]: daily xx monthly yy to specify to keep rrd files for xx days, and the 1st of each month for yy months. Note that if xx and yy are zero, no archiving occurs. You can also use routers.cgi*Archive[targetname]: no to disable archiving of a target. If no archives exist for a target, then the archive selection box will not appear. Defaults for the cfgfiles and expiredaily/expiremonthly settings can be located in the [archive] section of the routers2.conf file. ------------------------------------------------------------------------------ Q. How do I make routers.cgi work with SpeedyCGI? A. Modify the script to use #!/usr/bin/speedy -- -M10 -t3600 -r500 Then, in the routers2.conf, in the [routers.cgi] section, put the directive cache = yes This will cause the .cfg files to be cached between instances. WARNING: if you modify the .cfg files, it will NOT BE NOTICED. You will need to wait for the speedycgi timeout (1 hour in this setup) or execution limit (500 times) before they are re-read, and they may come back outof synch until all instances restart. The best thing is to touch the routers2.cgi script (touch cgi-bin/routers2.cgi) to force speedycgi to reload it immediately. ------------------------------------------------------------------------------ Q. How do I make routers.cgi work with mod_perl? A. First, configure your web server to use mod_perl on this script. Then, in the routers2.conf, in the [routers.cgi] section, put the directive cache = yes This will cause the .cfg files to be cached between instances. WARNING: if you modify the .cfg files, it will NOT BE NOTICED. You will need to restart your web server so that it restarts the mod_perl instances. ------------------------------------------------------------------------------ Q. How can I use the trend analysis? A. You can install the trend.cgi script found in the extras directory into your cgi-bin. Make sure you make the necessary changes for your perl location, and work directory, as described in the comments. If you then add the line trendurl = /cgi-bin/trend.cgi to your [routers.cgi] section of the routers2.conf, or add the line routers.cgi*Extension[targetname]: "Trend Analysis" /cgi-bin/trend.cgi graph-sm.gif to your MRTG .cfg files for each appropriate targetname, you should get a new link at the bottom of the graph for viewing trending analysis. trend.cgi does not require the SNMP community string, so you do not need to add the 'insecure' keyword and your community string is not revealed. ------------------------------------------------------------------------------ Q. How can I add multiple language support? A. First, download the language pack from the web site. Next, install the lang_xx.conf files you need in the same directory as your routers2.conf file (you can change this dir using langdir= in routers2.conf) Then, copy the xx icon directory to your rrdicons/xx directory. There may not be a special xx icon directory for all of the languages. Do not overwrite the default icons in the rrdicons directory! Finally, you should use the 'language = xx' option in the ruoters2.conf to set the default language to xx. This can be done globally or on a per-user basis. Individual users can also set a language in their Preferences. ------------------------------------------------------------------------------ Q. How do I create a new language pack? A. Download the lang_en.conf template language pack (English UK) from the website. You can then change the various icons and messages in the conf file. When yuo have finished, email the pack back to me, so that it can be included in the next release of the language pack? ------------------------------------------------------------------------------ Q. How can I run my MRTG installation seamlessly over multiple servers? A. First, install MRTG, RRDTool, your web server and routers2 on all the servers, and make sure that they work. Next, split your MRTG .cfg files between the different servers. On all servers, keep the same subdirectories. So, for example, on server A you might have a1/foo.cfg, a1/bar.cfg, a2/fish.cfg and on server B you can have b1/cheese.cfg Check that these are all working correctly in isolation. Now, you need to make the links between the servers. On each server, create cfg files corresponding to the cfg files on the other servers, which should contain the line routers.cgi*Redirect: http://otherserver/cgi-bin/routers2.cgi to specify the routers.cgi URL on the server which holds the real cfg file. So, in the above example, you would need to create b1/cheese.cfg on server A which would specify http://B/cgi-bin/routers2.cgi and then create a1/foo.cfg a1/bar.cfg and a2/fish.cfg on server B which should point to server A. The Devices menus on both servers should now look the same, except that the links will sometimes redirect you between servers. WARNING: Make sure that you have the same routers2.conf file on all servers! WARNING: Do not create a circular redirect. This is a Bad Thing. ------------------------------------------------------------------------------ Q. How do I get multi-level grouping in the Devices menu? A. This is in BETA. It may change in later releases. First, enable this with the 'multilevel = yes' directive in the [routers.cgi] section of your routers2.conf Next, make sure the [targetnames] for each of your defined groups is named in this fashion: /path/to/files = Groupname:Groupname This will spearate group heirachies according the the COLON in the group descriptions. THE PATH IS IRRELEVANT IN DEFINING GROUP HEIRACHIES. You can redefine the separator character (by default, a colon ':') by using the 'groupsep = x' directive to set it to x. Therefore, if you set it to the path separator character, you can have the simple group path name as the group description -- you may wish this if you have not already redefined the group names in the [targetnames] section. ------------------------------------------------------------------------------