When you first invoke provision, you see the window shown in Figure 4-1, in the standard Silicon Graphics desktop format. (See the section titled “Managing Windows” in the IRIS Essentials guide for complete information on the facilities of desktop windows.)

Figure 4-1. The provision Window

There are two main tools you can select from this window, pvcontrolpanel and pvgraph. These tools and their subordinate tools are discussed in the sections titled “Using pvcontrolpanel,” “Using pvcontrol,” and “The MIB Browser.” To invoke a tool, place the cursor over the desired icon and double-click the left mouse button. The icon changes color when you select it, and the ``carpet'' underneath the icon moves up to show that the invocation was successful and a new tool window appears on your screen. Each of these tools is detailed in its own section below.

There are four menus available on the pvcontrolpanel menu bar. The menus and their choices are listed below.

The File Menu contains options dealing with the pvcontrolpanel configuration files and contains the options to restart and quit the session. The following choices are provided:

The Hosts Menu allows you to control the arrangement of the hosts in your pvcontrolpanel window. The following choices are available:

Icons in the Hosts section represent each host that is currently communicating in some way with provision. A new icon is not added for each addition item monitored on a listed host unless it is specifically requested with the “Add Icon” menu choice. Also, host and collection icons can be dragged from the propel graphical tools (described in Chapter 2, “Software Distribution, User and Host Management With propel”) or from the IndigoMagic desktop and tools, and can be dropped into the Hosts area of pvcontrolpanel.

The Items Menu contains options dealing with the operation of the pvcontrolpanel activity. An Item is any configured monitoring unit, for example, monitoring a script on a particular host at a particular interval. The following choices are provided:

The Help Menu invokes the online help utility to provide help on all aspects of using provision.

When you select the “Show Available Variables and Scripts” choice from the Variables menu (or from the Configure One Graph window in pvgraph), you see the window shown in Figure 4-3.

Figure 4-3. The Available Variables and Scripts Window

This window lists available MIB variables that can be monitored in the upper half, and all available monitoring and notification scripts in the lower half. You can monitor MIB variables not listed in this window, but they must be specified by their full numeric Object ID (for example, the sysServices variable has an Object ID of 1.3.6.1.2.1.1.7.0). You can also monitor any script you have created that is not represented in this window, but it must be specified with its full name. For example, the snmpGet script's full name is provision:snmpGet.

The MIB variables are described in the MIB file. To see a variable's description, select the MIB browser from the Add One Graph window (in pvgraph) or select “MIB Browser” from the Variables menu in pvcontrolpanel.

Once the browser is up, press the Variable... button and enter the name of the variable you wish to have described in the Name field. Then, select the “Description” menu option from the Help menu of the Variable window. A new window appears, showing the description text. For example, Figure 4-4 shows the description window of the sysDescr variable.

Figure 4-4. Description Window for the sysDescr Variable

This procedure is also described in the section titled “Obtaining Descriptions of Variables” in this chapter.

The provision application retrieves data from remote machines through commonly used protocols including rstat and SNMP. The provisiond daemon has an embedded sgitcl interpreter and uses sgitcl scripts to retrieve remote information.

When a request is made for a new sgitcl script from pvgraph or pvcontrolpanel, the provisiond daemon creates a new, private copy of the sgitcl interpreter. The daemon then calls a predefined script called provision:wrapper to gather the script information and return it. If the requested script is a valid SNMP Object ID, the routine provision:snmpGet is called to do the retrieval. If the script is a custom file you have created, provision:wrapper executes the file to retrieve the script data. Finally, the wrapper calls the script as an internal sgitcl routine which can be in any sgitcl tlib library.

You must create a file with a name ending in .tlib in the /usr/IRIXpro/lib directory to hold your sgitcl script in order for provision:wrapper to locate the new script and call it as an sgitcl routine.

Your scripts are not required to be written in sgitcl. If your new script is not an sgitcl script, simply place the full pathname of the executable program or script in the /usr/IRIXpro/provision/scriptDefs file.

A description of each script must be placed in the file /usr/IRIXpro/provision/scriptDefs. This description is used to determine the type of any arguments, and the type of the return data from the script. If a script is customized or a new script is added, then this file must be updated. A description of each new MIB variable must be placed in the file /usr/IRIXpro/provision/varDefs.

host-list [argument]. . . 

This area of the pvcontrolpanel main window lists all hosts and collections currently being monitored by or otherwise known to your provision session. An icon appears with each host's name. You can double-click a host icon and a dialogue window appears showing the items currently being monitored and any alarms received for the host or collection.

When an alarm comes in on a monitored host or collection, the object icon turns red to show you that an alarm has been received. When you double click the icon to view the alarm, the icon turns orange to show the alarm has been noted. If you then click the Clear Alarms button on the dialogue window, the icon returns to its default color.

All the items currently being monitored on any host are listed in this area. You can select which item is displayed in the Script Configuration Area and start and stop any item by clicking the provided buttons for each item being monitored.

The script configuration section of the pvcontrolpanel window is functionally identical to the script configuration window used with pvgraph. This window is discussed in the section titled “The New Graph Window.” Some key differences are:

To create a log file with pvcontrolpanel click the button labeled log when you configure a variable or script. The name of the log file used appears at the top of the Items to Monitor section.

When you wish to review the log you must select the Close Log File menu option from the Items menu or stop the actual logging . In order to stop all logging, close the log file, and not open a new log file, you must stop monitoring all items currently configured, delete all the items currently configured, and select the Close Log File menu option.

Alternately, you can select Close Log File from the Items menu, and the log file for the selected item will be closed and a new one opened. You can then review the log that was closed. This method is recommended.

---

Note: If you change the host or parameter being logged with a modify command, the log file will not be restarted, nor will it register this change in any way. Thus, when the log is viewed it will be presented as if the parameters had not changed, and any information collected after the change is attributed to the initial configuration.

---

To create a log file with pvcontrol you must select logging as a command line option when you use the add or modify commands to select a variable or script. The name of the log file used is displayed in the following manner:

The log file is:/usr/IRIXpro/provision/Logs/0.950201-22:34:26

When you wish to review the log you can stop all monitoring action by deleting all items and entering the closeLog command at the pvcontrol prompt to stop all monitoring and logging, or you can simply enter the closeLog command and the current log file will be closed and a new one opened.

---

Note: If you change the host or parameter being logged with a modify command, the log file will not be restarted, nor will it register this change in any way. Thus, when the log is viewed it will be presented as if the parameters had not changed, and any information collected after the change is attributed to the initial configuration.

---

The File menu has the following choices:

The Graphs menu has the following choices:

The Help menu offers online help with pvgraph.

When you select the menu choice to add a graph to your pvgraph window, you see the new window shown in Figure 4-6.

Figure 4-6. The New Graph Window

This window has several fields for you to fill in the parameters of the graph you wish to make. There are also other fields that may appear as you enter information. Certain scripts require more parameters than others, and if you enter the name of such a script in the Script field, additional fields appear below the basic fields. The fields require the following kinds of information:

At the bottom of the New Graph window, there are five buttons, labeled Show Available Vars, MIB Browser, Apply, Accept, and Cancel. The Show Available Vars button brings up the Available Variable and Script window, described in the section titled “The Available Variable and Script Window.” The SNMP Browser button brings up the Browser, described in the section titled “The MIB Browser.” Use the Apply button to add your graph and leave the New Graph window on the screen, or the Accept button to add the new graph and remove the New Graph window. The Cancel button removes the New Graph window without applying your changes.

If you add additional graphs, the window is subdivided for each graph. When you have more graphs than can fit on the window, you must enlarge the window to accomodate the new graphs.

When you have applied your graph to the pvgraph main window, the center of the window looks something like that shown in Figure 4-7.

Figure 4-7. The pvgraph Window With One Graph

Note that there is a check box and a slider present at the bottom of the pvgraph window. When you begin your graph, the check box has a check mark, indicating that the graph being made is using data as it is collected in real time. The slider is grayed-out and inoperable. At any time you can click on this check box and the entire history of the graph is made available to you. The slider bar becomes active and you can use it to review your graph. When you wish to return to live graphing, simply click the check box again and the graph is updated. No data is lost during your review operation.

Working With Graph Alarms

When the script results or variable values being graphed exceed the low and high limits you specified when you added or modified the graph, an alarm is set off for you. This alarm is a visual cue to check the item being graphed. When the value of the script or variable has gone out of bounds, the graph turns red, as shown in Figure 4-8.

Figure 4-8. A Graph With an Alarm Showing

To clear alarms, select the Clear Alarms menu option from the Graphs menu. If you select the Show Alarms option, a window appears with a log of all alarms received since the last Clear Alarms command, or since the beginning of the pvgraph session.

The Graph Parameters Window

When you select the “Change Parameters of All Graphs” menu item from the pvgraph Graphs menu, you see the new window shown in Figure 4-9.

Figure 4-9. The Graph Parameters Window

What you are changing is the period of graph-time that is displayed in the window at any given moment. The parameters you can change are the graph width value and the time unit. The width value is simply the number of increments of the selected time unit. In the above example, the width value is 1 and the time unit is minutes for a width of 1 minute. You may select 1, 2, 5, 10, 20, or 30 for the width value, and one of seconds, minutes, hours, days, or weeks for the time unit.

Once you have made your selections, you may press the Apply button to apply the change and leave the Graph Parameters window on the screen, or the Accept button to apply the changes and remove the Graph Parameters window. The Cancel button removes the window without applying your changes. The Help button invokes provision's online help utility.

The Graph Style Window

If you select the “Change Style of Selected Graph” menu item from the Graphs menu in pvgraph, you see a new window on your screen, as shown in Figure 4-10.

Figure 4-10. The Graph Style Window

This window allows you to select and modify the way the selected graph is presented in pvgraph. When the polling interval arrives on a graph, the new value of a variable (or the value of the output of the script being graphed) is placed on the graph as a point, and a line is drawn between the new point and the previous point. You may select the shape of the point marker, its size and color, and the style, width, and color of the connecting line. Click the style of marker and line you prefer. Any valid X color or value may be named in the Color field, and you can use the arrow buttons to increase or decrease the size of the line or marker.

When you have made your selection, press the Apply button to apply the new format to your graph, or the Cancel button to discard your unapplied changes.

At any time during your pvcontrolpanel or pvgraph session, you can save the current graphing and/or monitoring selections in a configuration file. The options are in the File menu in both utilities:

Read Config...
Save Config
Save Config as...

When you first save your current state, use the “Save Config as...” option. When you select this option, you see a file selection window for your current working directory, such as that shown in Figure 4-11.

Figure 4-11. A File Selection Window

Select a new filename for your configuration file and click the OK button when you are satisfied with your selection. Your current state is now saved. If you wish to save your current selections again later, using the “Save Config” option from the Files menu of pvcontrolpanel or pvgraph will automatically bring up the file selection window with the most recently used config file specified. You can, however, change the name so as not to overwrite the existing config file. Using config files, you can create templates for commonly used monitoring and graphing scenarios. For example, you can have preset configuration files to monitor all systems' network traffic or the swap rates on your servers.

Each provision configuration file is written in clear text and looks similar to the following example:

# provision config file written Mon Feb  6 14:29:52 PST 1995 by pvcontrolpanel
off on off  random provision:random  wookie 1 {}  -1 0 {200} 
off on off  ifInOctets_1 1.3.6.1.2.1.2.2.1.10.1  wookie 1 {}  10 0 {2} {3} 
off on off  ifOutOctets_1 1.3.6.1.2.1.2.2.1.16.1  wookie 1 {}  10 0 {2} {3} 
off on off  random provision:random  irixpro 5 {}  600 0 {100} 

You can view log files created with pvcontrol or pvcontrolpanel using pvgraph. For more information on log files and how they are created, see “Creating a Log File With pvcontrolpanel” or “Creating a Log File with pvcontrol” in this chapter. A log file is simply a file containing a series of values for a script or variable accumulated over a period of time. The provision application stores the log files in the log directory /usr/IRIXpro/provision/Logs. A log file is actually contained in two filenames in that directory. For example, a log might be placed in filenames similar to 0.950201-21:18:33.Desc, and 0.950201-21:18:33.Data. Filenames ending in .Desc contain information about what was logged, and filenames ending in .Data contain the actual log information.

To view a log as a graph, use the command syntax

pvgraph filename 

to invoke pvgraph in log file mode. The filename argument can be any of the three filenames that refer to the desired log. For example, using the example filenames as shown above, you could invoke pvgraph in these ways:

pvgraph 0.950201-21:18:33 
pvgraph 0.950201-21:18:33.Desc 
pvgraph 0.950201-21:18:33.Data 

Each of the above commands results in the same action by pvgraph. By default, pvgraph looks for the given filename in /usr/IRIXpro/provision/Logs, but you can specify any log file in any directory by issuing the pathname of the file on the command line.

When you invoke pvgraph with a log file name as a command line argument, pvgraph does not connect with the provisiond daemon as usual. Instead, the named log file is loaded. The log is not displayed as a graph, though, until you use the Add A Graph menu option from the Graphs menu. When you use this command, you see a different New Graph window, similar to Figure 4-12.

Figure 4-12. The New Graph Window with Log File Information

When you view a log file, it does not scroll by as usual; you must use the slider at the bottom of the window to move forward and back throughout the log.

If you are invoking pvgraph from the desktop or directory view rather than as a shell command, you can drag the file icon for the log you wish to view and drop it on the pvgraph icon and pvgraph will come up with the log loaded.

Browser uses Simple Network Management Protocol (SNMP) agents to obtain information. The SNMP agent for Silicon Graphics workstations is snmpd(1M). Vendor-specific SNMP agents are used to obtain information about other types of nodes (see Figure 4-13). For more information on SNMP see the section titled “SNMP Management Glossary.” For information on enabling SNMP agents, see “Enabling SNMP Agents.”

Figure 4-13. SNMP Agents and Browser

chkconfig -f snmpd on 

ps -e | grep snmpd 

snmpd 

rsh guest@tahoe 'ps -e | grep snmpd' 

accept sequoia:* 

accept  *:public/get

To start Browser, click the browser button from a provision window.

The Browser main window appears. An example is shown in Figure 4-14.

Figure 4-14. Browser Main Window

The entry fields in the Browser main window enable you to specify the node you wish to browse, a community string, a time-out value for accessing the SNMP agent on the node, and the number of retries to make when attempting to access a remote node.

When you invoke Browser, the entry field shown in Figure 4-15 contains the name of your workstation. You can replace it with the name or address of the node you want to browse. A blank entry field is the same as specifying the name of your workstation.

Figure 4-15. Node Entry Field

The Community entry field shown in Figure 4-16 contains the community string that is to be used in the SNMP packets sent to the node. The community string is an authorization password for the node you browse on. On Silicon Graphics workstations, valid community strings and other authorization information is specified in the file /usr/etc/snmpd.auth. The default community string on Silicon Graphics workstations is “public”. For other types of nodes, such as routers and bridges, the community string is specified for each device by a system administrator. A valid community string must be supplied in order to use Browser to view MIB information.

Figure 4-16. Community Entry Field

If Browser doesn't receive a reply from the SNMP agent on the specified node within the time-out value, it will try again. The default time-out value, shown in Figure 4-17, is 5 seconds.

Figure 4-17. Timeout Interval Entry Field

The Number of retries entry field, shown in Figure 4-18, specifies the number of retries when there has been no reply from the node. The default is 3.

Figure 4-18. Number of Retries Entry Field

The mib-2, enterprises, and experimental buttons in the Browser main window, shown in Figure 4-19, provide quick ways to specify what you want to browse: the mib-2 MIB, or the enterprises or experimental nodes in the SNMP Containment Tree, respectively. When you click these buttons, a Subtree window appears. Subtree windows and Table windows are described in the next section. These buttons are grayed out if no MIB specifications in that portion of the SNMP Containment Tree are available to Browser. The term ``grayed out'' means that the button title is gray at that moment, rather than black. This indicates that the function or service represented by that button is unavailable.

Figure 4-19. mib-2, enterprises, and experimental Buttons

When you click the Variable... button, shown in Figure 4-20, a Variable window appears. This window is used to get and set the values of specific MIB variables. It is explained in detail in “Obtaining and Setting Values Using the Variable Window” in this chapter.

Figure 4-20. Variable... Button

To display MIB information, Browser uses two types of windows: Subtree windows and Table windows. For every nonleaf node in the SNMP Containment Tree, Browser displays one of these types of windows:

The remainder of this section discusses examples of these windows.

Subtree Windows That Show Subtrees

Figure 4-21 shows the Subtree window for mib-2. It is an example of a Subtree window for a subtree that contains other subtrees.

Figure 4-21. Subtree Window Showing Subtree Objects

The Node entry field, shown in Figure 4-22, contains the node name or address you specified in the Browser main window.

Figure 4-22. Node Entry Field

The Object ID and Name entry fields, shown in Figure 4-23, contain two different representations of the name of the subtree displayed in the window. The Object ID entry field contains the numeric representation of the name (dot separated object numbers) and the Name entry field contains the text string representation (dot-separated object names).

Figure 4-23. Object ID and Name Entry Fields

The scrolling display area in the center of the window contains one line for each object in the subtree, such as the udp line shown in Figure 4-24. The line begins with the object's number in curly braces followed by its object name. Clicking the Open group... button brings up a Subtree window for the object on this line. Its use is described more fully in “Navigation Using Buttons in the Subtree and Table Windows” in this chapter. A grayed-out button means there are no variables under this object in the MIB.

Figure 4-24. Object in a Display Area

The Read At line provides status information during a “Get” operation (see “Obtaining, Setting, and Saving Variable Values” in this chapter), which is replaced by the current time after the operation is completed. An example is shown in Figure 4-25.

Figure 4-25. Read At Line

The current time is displayed on the Set At line after a “Set” operation (see “Obtaining, Setting, and Saving Variable Values” in this chapter). An example is shown in Figure 4-26.

Figure 4-26. Set At Line

Checking the “Close this window when opening a subwindow” check box, shown in Figure 4-27, specifies that you want this Subtree window to be closed when a new Subtree or Table window for a node in this subtree is opened. By default, each of the Subtree or Table windows you open for subtrees or tables within this subtree will have the same setting.

Figure 4-27. Close This Window When Opening a Subwindow Check Box

Subtree Windows That Show Variables and Tables

Figure 4-28 shows the Subtree window for mib-2.udp. It is an example of a Subtree window that shows the variables and/or tables of that subtree (in MIB terminology, this type of subtree is called a group).

Figure 4-28. Subtree Window Showing Variables and a Table

Most portions of this type of Subtree window are the same as the Subtree windows described in “Subtree Windows That Show Subtrees” in this chapter. However, the display area of this type of Subtree window contains entry fields and Open table... buttons rather than Open group... buttons.

Variables in the subtree are shown in the display area as an object number, an object name, and an entry field, as shown in Figure 4-29. When the object number (in braces) is appended to the object ID at the top of the window, it forms the complete object ID for the object. The entry field is gray for variables whose values are defined as read-only in the MIB and pink for variables that are defined as read-write or write-only in the MIB. If the entry field is pink, you can set the value of that variable (see “Obtaining and Setting Values Using the Edit Menu of a Subtree Window,” in this chapter).

Figure 4-29. Variable Line in a Subtree Display Area

Tables in the subtree have lines that include their object number, their name, and the Open table... button, as shown in Figure 4-30. When you click an Open table... button, a Table window, described in the next section, appears.

Figure 4-30. Table Line in a Subtree Display Area

Browser Table Windows

Figure 4-31 shows the default Table window for mib-2.udp.udpTable. When a Table window appears, the display area contains only the names of the table variables. Entry fields appear for the variables as you retrieve their values with “Get next row” in the Edit menu. (See “Obtaining and Setting Values Using the Edit Menu of a Table Window,” in this chapter.)

Figure 4-31. Browser Table Window

With Browser you can open a Subtree window for each subtree in an MIB that you want to browse and a Table window for each table in an MIB that you want to browse. Browser buttons and menus enable you to specify the subtree or table you want to view. When you use these buttons and menus, you are “navigating” the MIB Tree. The three navigation methods are described in the following sections.

To get a description of each of the objects in a subtree or each of the variables in a table, select “Description” from the Help menu of the Subtree or Table window. A Description window appears. Figure 4-33 shows an example.

Figure 4-33. Description Window

Browser enables you to obtain the values of MIB variables and set them if you have write access. (Write access is determined by the type of the variable and by your community. See “Authorizing Browsing” and “SNMP Management Glossary.”) Three types of Browser windows can be used to get and set variables:

The File menu in each window gives you one or more of the window management and quitting choices listed below.

This section contains an example Browser session on a network that contains a Cisco router with IP address 192.26.51.27.

To begin this session, invoke Browser through provision.

The Browser main window is placed on the screen. To browse the MIB for the Cisco router, first fill in the entry fields in the Browser main window:

Figure 4-36 shows the Browser main window after you've filled in the entry fields.

Figure 4-36. Example Browser Main Window

Suppose you want to get the values for the lsystem group in the Cisco MIB. To display the variables in this group, use the Navigate rollover menus to navigate through the MIB hierarchy to lsystem, as shown in Figure 4-37.

Figure 4-37. Navigate Rollover Menus for cisco.local.lsystem

When you release the mouse button, the cisco Subtree window shown in Figure 4-38 appears:

Figure 4-38. Subtree Window for cisco.local.lsystem

To get the values for these variables, select “Get” from the Edit menu. The entry fields for the variables are filled in with their current values, and the current time is indicated at the bottom of the window. Figure 4-39 shows an example:

Figure 4-39. Subtree Window With Values for cisco.local.lsystem

Use the right scroll bar to adjust the display area so that you can examine the values of the variables that don't fit in the default-size display area.

This section describes some basic terms used in the SNMP management framework. It begins with basic concepts. Later definitions build on terms defined previously. Terms in italics are defined elsewhere in this section.