Home

	Expand Search

SNMP SubAgent User's Guide (UNIX)

Chapter 3: Using the Subagent

Chapter 3

The SQL Server SNMP Subagent allows you to monitor characteristics of SQL Servers and Open Servers using network management products.

This chapter describes:

• How the Subagent works
• How to set up the Subagent initialization file
• How to start the Subagent
• How to shut down the Subagent

  Note: You cannot use network managers to modify SQL Server characteristics.

How the Subagent Works

The Subagent monitors high level characteristics of SQL Servers and Open Servers by polling the servers at regular intervals. To identify which servers to monitor and how often to collect information, the Subagent reads its initialization file. By default, the initialization file is snmp.ini, but you can name it anything you want. However, this document refers to the initialization file as snmp.ini.

When you start the Subagent, it:

• Connects EMANATE to let it know which objects it is managing.
• Reads its initialization file to identify polling intervals to use and to determine which servers to contact.
• Contacts each server and extracts information. Each piece of information the Subagent extracts is represented by an object in the RDBMS MIB, the Network Services MIB, or the SYBASE MIB. The Subagent maintains this information internally so that network managers can access it or modify it. The Subagent maintains this connection for as long as the server and the Subagent are running.
• Writes database information to snmp.ini. The Subagent extracts database information from each SQL Server and puts some of this information in snmp.ini.
• Periodically updates MID information and snmp.ini with new database information. Also, the Subagent modifies polling intervals and the server monitoring list based on requests from network managers.

Figure 3-1 depicts the communication between the Subagent, the network manager, the master agent, the servers, the interfaces file and snmp.ini:

Figure 3-1: SQL Server SNMP Subagent configuration

Note: Sometimes, a server may be down when the Subagent attempts to contact it. In this situation, the Subagent attempts to contact the server during each LongSleep polling cycle.

Setting Up the Subagent

Subagent initialization file is snmp.ini. This file:

• Identifies which SQL Servers and Open Servers the Subagent is going to manage
• Controls how often the Subagent collects information from the servers

Sybase recommends that you do not use a single Subagent to monitor more than five servers. If you do, you may encounter performance issues due to network traffic and polling intervals.

The following sections describe how to create the initial version of snmp.ini, the format of entries in snmp.ini, and the different ways to modify snmp.ini.

Note: As part of the installation, you create an initial version of snmp.ini. If you did not install the Subagent, contact the individual who did to locate this initialization file.

Monitoring Servers on Remote Hosts

Sybase recommends that you install EMANATE and the Subagent on the same host machine that has the servers you want to monitor. Sybase does not recommend using the Subagent to monitor servers on a different host because:

• applUpTime, applLastChange, and applLastInboundActivity, will be inaccurate because the Subagent generates this value based on the local host's system time.
• applDirectoryName will be incorrect because the Subagent generates this value based on the Subagent's definition of the SYBASE environment variable.
• There may be performance issues due to network traffic and polling intervals.

See Chapter 4, "Objects in the Network Services MIB and RDBMS MIB" for information on these objects.

Creating snmp.ini

To create snmp.ini you use snmpconfig. The following sections describe what you need to know before you can use snmpconfig and how to use snmpconfig to create snmp.ini.

WARNING! If you already have a version of snmp.ini, you probably do not want to use snmpconfig again. When you use snmpconfig, it overwrites the existing file; you cannot use snmpconfig to modify an existing file. To update an existing file, see "Modifying snmp.ini".

Before You Use snmpconfig

To create entries in snmp.ini, snmpconfig reads your interfaces file to determine which servers it can access. To create valid entries in snmp.ini, you need the following information:

• Path and name of the initialization file you want to create. By default, snmpconfig creates snmp.ini in the $SYBASE directory.
• Path and name of interfaces file you want to use. By default, snmpconfig uses the interfaces file in the $SYBASE directory.
• Login for each server from which the Subagent collects data.
• Password of each login.
• Host name or IP address of host on which SQL Servers or Open Servers reside if they are not on the same host as where you start snmpconfig.

  Note: Sybase does not recommend that you use the Subagent to monitor servers on remote hosts. See "Monitoring Servers on Remote Hosts" for more information.

After you start snmpconfig, the utility:

1. Reads the interfaces file.

2. Determines if any servers in the interfaces file reside on the same host from which you started snmpconfig. If there are no servers on the same host, asks you for a different host name to use.

3. For each server on the host, snmpconfig asks you if you want to monitor the server. When you answer yes, snmpconfig asks you for a login and password on the server. The Subagent uses this login to collect information from the server.

The following example depicts a sample session with snmpconfig. In this example, bold-faced text depicts typical user input.

snmpconfig

Welcome to the Sybase SNMP Agent configuration Procedure

$SYBASE is /usr/local/system1001

Checking interfaces file for Sybase Servers on host squonk......

Server GABRIEL on squonk IP Address 157.111.124.6 was found.

Do you want this agent to monitor GABRIEL?(y/n):y

Enter the login name to be used by the agent to GABRIEL.

Recommend  'sa' for SQL Servers 4.x  and 'SNMP' for all others.

Enter login name: SNMP

Enter Password for SNMP [NULL for no password]:

Enter SNMP Password again:

Using snmpconfig

To use snmpconfig to create snmp.ini:

1. Enter the following command:

   snmpconfig [-c ini_file] [-I interfaces_file]

   where ini_file identifies the path and name of the file you want to create and interfaces_file identifies the path of the interfaces file you want snmpconfig to use. If you do not use the -c flag, snmpconfig creates snmp.ini in the $SYBASE directory. If you do not use the -I flag, snmpconfig uses the interfaces file in the $SYBASE directory.

2. Respond to the prompts from snmpconfig.

   Note: When you respond to a yes or no prompt, use "y" for yes and "n" for no. When you enter a password, snmpconfig does not display the characters you enter on the screen.

Modifying snmp.ini

There are two ways you can modify the entries in snmp.ini: by editing snmp.ini with a text processor or by setting their values using your network manager. Using your network manager, you can modify polling intervals, modify passwords, add server entries, and remove server entries from snmp.ini.When you set an object representing an entry in snmp.ini, the Subagent writes the new value to snmp.ini.

Before you edit snmp.ini, you must shut down any Subagent that is using the file. If you do not, changes you make may be lost if the Subagent updates the file. See "How the Subagent Works" for more information.

Format of snmp.ini

There are two sections in snmp.ini: a monitoring interval section and a server list section. The format of all entries must conform to the following rules:

• Each section must begin with a server name enclosed within brackets.
• Each section contains a set of keyword=value pairs.
• Keywords cannot contain spaces, commas, brackets, semicolons, or equal signs.
• One or more keyword=value pairs can appear under each section.
• If you repeat a keyword=value pairs for the same server, the Subagent ignores the first entry and uses the second entry.
• keyword=value pairs cannot extend to more than one line.
• To insert a comment line, begin the line with a semicolon. A comment can be on a line by itself or it can follow an entry.

Setting Polling Intervals

You set all polling interval information in the [SNMP$GENERAL] section of snmp.ini. There are two variables that determine how often the Subagent collects information:

• ShortSleep=seconds-the time in seconds between data polls. For example, the following entry:

  ShortSleep=600

  directs the Subagent to collect data from the servers every 600 seconds. The default value for ShortSleep is 300 seconds. If you modify ShortSleep, you must use a value between 10 and 1800 seconds, inclusive. Sybase recommends a value of 40 or higher if the Subagent is monitoring multiple servers.

• LongSleep=number-identifies the number of ShortSleep cycles that will occur before a LongSleep data collection occurs. For example, the following entries:

  ShortSleep=600
  LongSleep=5

  direct the Subagent to collect LongSleep information every 3000 seconds (600 * 5). The default value for LongSleep is 4. If you modify LongSleep, you must use a value between 1 and 20, inclusive.

The following is an example of the polling interval section in snmp.ini:

[SNMP$GENERAL]
ShortSleep=600
LongSleep=5

See "Objects and Polling Intervals" for more information on the types of information the Subagent collects during ShortSleep and LongSleep polling intervals.

Creating Server Entries

Each server that you want the Subagent to monitor must have its own section in snmp.ini. You identify a section for a server with a [server_name] keyword, where server_name is the name of the server. For example, the following entry:

[PRODUCTION_SQL_SERVER]

identifies the beginning of the Production SQL Server section. All entries that appear below [PRODUCTION_SQL_SERVER] belong to this server definition. server_name is case-sensitive and must match the entry in the interfaces file.

Sybase recommends that you do not use a single Subagent to monitor more than five servers. If you do, you may encounter performance issues due to network traffic and polling intervals.

There are up to six keyword=value pairs that can appear for a server entry:

• LoginName=name-the login the Subagent uses to log on to the server. This entry is optional. If you do not use this entry, the Subagent uses "SNMP" as the login.
• PassWord=password-the password for the login in a human readable format. To indicate that the login does not have a password, set password equal to "NULL". For example:

  PassWord=NULL

  If there is a PassWord entry for a server, you should not have a passX entry for the same server. For more information, see "Modifying Server Passwords".

• passX=scrambled-the password for the login in a secure format. If there is a passX entry for a server, you should not have a PassWord entry for the server. For more information, see "Modifying Server Passwords".
• Version=server_type-the type of server where server_type can be "SQL Server" or another string. If the entry does not contain "SQL Server," the Subagent treats it as an Open Server. For Open Servers, server_type must be less than 119 characters. The value you specify for server_type appears in the applTable as applVersion. This entry is optional.
• applIndex=number-an integer between 1 and 99999 that identifies the application index number for the server. Each managed object monitored by the Subagent must have a unique number on a host. If you are using other sub-agents on the same host, you should coordinate the numbers in this list with the index numbers in other sub-agent initialization files.
• ServerContact=name-the name of the contact person responsible for the server. This entry is optional. The name appears in the rdbmsSrvTable as the rdbmsSrvContact.

The following is an example of SQL Server and Open Server entries in snmp.ini:

;The following entry defines a SQL Server
[PRODUCTION_SQL_SERVER]
apllIndex=15
loginname=SNMP
PassWord=agent
version=SQL Server

;The following entry is for an open server
[PRODUCTION_SERVER]
apllIndex=16
loginname=SNMP
PassWord=agent
version=Open Server

After you start the Subagent, it connects to each server in snmp.ini using the login and password. For each SQL Server, the Subagent extracts database information and inserts the following three entries into the appropriate server section:

• dbname=name-the name of a database managed by SQL Server.
• dbid=number-the database identification number as stored in the master...sysdatabases table.
• dbcontact=name-the name of the database owner.

The following is an example of snmp.ini after the Subagent inserts database entries for a SQL Server:

;The following entry defines a SQL Server
[PRODUCTION_SQL_SERVER]
apllIndex=15
loginname=SNMP
PassX=ABCDEFGHIJKLMNOPQRSTUVWXYZ
version=SQL Server

;The following entries are for each database
;that PRODUCTION_SQL_SERVER manages
dbname=master
dbid=1
dbcontact=sa

dbname=pubs2
dbid=2
dbcontact=Mackenzie Anya

dbname=test
dbid=3
dbcontact=Willy Brodeur

;The following entry is for an open server
[PRODUCTION_SERVER]
apllIndex=16
loginname=SNMP
PassX=ABCDEFGHIJKLMNOPQRSTUVWXYZ
version=Open Server

Modifying Server Passwords

Each server monitored by the Subagent must have a login for the agent to use. When you initially created logins in snmp.ini, snmpconfig took the password you entered and converted it into a secure format. Secure passwords are preceded by the keyword passX=.

To modify a password, you must replace the passX= entry with a new PassWord= entry. The next time you start the Subagent, the Subagent reads snmp.ini, converts the human readable password to a secure non-readable password, and then replaces the PassWord= entry with a passX= entry. Only the Subagent can decipher these passwords.

Creating Logins

For the Subagent to monitor SQL Servers or Open Servers, each server must have a login that the Subagent can use. The Subagent uses this login to collect information from the servers.

For SQL Server release 4.9.2, the Subagent must be able to use the "sa" login. For SQL Server 10.x and higher, Sybase recommends that you create the login "SNMP". When you create a login on SQL Servers 10.x and higher, you must grant the login sa_role. On Open Servers, Sybase recommends that you create an "SNMP" login also. The Subagent does not need a login to access Backup Servers.

To create logins on SQL Servers 10.x and higher, Sybase provides the addSNMP.sql isql script. addSNMP.sql creates an "SNMP" login with a password of "airplane". If you want a different password, modify addSNMP.sql before you use it. This script is in the $SYBSNMP/scripts directory.

To use addSNMP.sql, enter the following command:

isql -Ulogin -Ppword -Sserver < $SYBSNMP/scripts/addSNMP.sql

where login is a login that has privileges to create logins on the server, pword is the login password, and server is the server on which you want to create the login.

Starting the Subagent

The following sections describe what you must do before starting the Subagent, how to start the Subagent, and how to shut down the Subagent.

Before You Start the Subagent

Before you start the Subagent, be aware of the following:

• You must start the master agent before you start the Subagent.
• You must be "root".
• It is generally a good idea to start the Subagent before you start your SQL Servers or Open Servers. This is because the Subagent monitors the length of time the server has been up and stores this information in the sysUpTime OID. If you start the Subagent after you start your servers, the Subagent cannot provide a value for sysUpTime.
• You must define the environment variables SYBASE, SYBSNMP, SR_MGR_CONF_DIR and SR_AGT_CONF_DIR. See "Defining Subagent Environment Variables" for more information on defining these environment variables.
• You must have $SYBASE/bin in your path.

Defining Subagent Environment Variables

You must define the following environment variables before you start the Subagent:

• SYBASE-identifies the SYBASE installation directory
• SYBSNMP-identifies the Subagent installation directory
• SR_AGT_CONF_DIR-identifies the master agent configuration directory

To set these environment variables, enter the following commands:

setenv SYBASE sybase_path
setenv SYBSNMP subagent_path
setenv SR_AGT_CONF_DIR /etc/srconf/agt

where sybase_path identifies the SYBASE installation directory, subagent_path identifies the Subagent installation directory, and conf_dir identifies the master agent configuration directory. Typically, the master agent configuration directory is /etc/srconf/agt.

Starting SQL Server SNMP Subagent

Before you start the Subagent, make sure that it is not already running. If the Subagent is already running and you try to start another, both Subagents will run simultaneously. This may cause errors if both Subagents are using the same initialization file.

The format of the Subagent command is:

sybagt        [-c ini_file] [-D] 
        [-e [log_file | stdout | stderr]]
        [-h] [-I interfaces_file] [-v]

where the command flags are:

• -c ini_file-identifies the path and name of the Subagent initialization file. If you do not use this flag, the Subagent looks for snmp.ini in the $SYBASE directory. If you use this flag but do not specify a path, the Subagent looks in the current directory for the file.
• -D-directs the Subagent to run in diagnostic mode. In diagnostic mode, the Subagent reads snmp.ini, attempts to contact all of the servers listed in snmp.ini, and then stops. If the Subagent encounters errors, it writes messages to the log file (see the -e flag). You do not need to be "root" to run the Subagent in diagnostic mode.
• -e log_file-directs the Subagent to write messages to the log file specified in log_file. If you do not specify a log file name, the Subagent uses sybagt.log in the /tmp directory. If you specify stdout instead of a log file name, the Subagent writes messages to standard output.
• -h-displays command usage help.
• -I interfaces_ file-identifies the path and name of the interfaces file you want to use.The interfaces file identifies the port numbers of the servers the Subagent is managing. If you do not use this flag, the Subagent uses the interfaces file in the $SYBASE directory. If you use this flag but do not specify a path, the Subagent looks in the current directory for the file.
• -v-displays the Subagent version string and then exits.

When you start the Subagent, you should run it in background mode. For example, the command:

sybagt &

starts the Subagent as a daemon process running in background mode.

Starting the Subagent at Boot Time

Sybase recommends that you automatically start the Subagent when you start your system. You can do this by putting the Subagent start command in your system startup file. The system startup file is different for each type of machine, but on machines running SunOS BSD the file is /etc/rc.local. Check with your System Administrator for the file that is appropriate for your environment.

Shutting Down the Subagent

To shut down the Subagent, you:

1. Identify the PID of the Subagent process. If you are on a machine using AIX, HP-UX, or SunOS SVR4, enter the command:

   ps -ef | grep "snmp"

   If you are on a machine using SunOS BSD, enter the command:

   ps -guax | grep "snmp"

   The ps command returns the PID for any active Subagent. If ps does not return a PID, the Subagent is not running.

2. Terminate the process with the command:

   kill -9 process_id

   where process_id is the PID.