Home

	Expand Search

SNMP SubAgent User's Guide (UNIX)

Chapter 2: Using EMANATE

Chapter 2

You must use the master agent EMANATE to communicate with the Subagent; you cannot use a different master agent to communicate with the Subagent. As part of the Subagent distribution, Sybase provides EMANATE.

This chapter describes:

• How EMANATE works
• How to configure EMANATE
• How to define nonstandard communication ports for multiple master agents
• How to start EMANATE
• How to use EMANATE's log file

This chapter does not describe the SNMP version 2 configuration files for EMANATE. See Appendix B, "SNMP Version 2 Configuration" for more information.

How EMANATE Works

EMANATE performs the following functions:

• Listens for PDU requests from the network manager
• Verifies that the network manager has privileges to set or get object information
• Verifies the syntax of PDU requests
• Sends verified PDU requests to the Subagent
• Returns responses to the network manager
• Sends traps to the network manager

When you start EMANATE, it determines which ports it should listen on for communication with the network manager. Typically, master agents listen on port 161 and respond on port 162. However, you can specify which ports you want EMANATE to use. See "Defining Nonstandard Ports" for more information.

After EMANATE starts, it reads the configuration file snmpd.cnf. This file contains configuration information on system variables, community specifications, and trap specifications. See "Configuring EMANATE" for more information on snmpd.cnf.

When you start the Subagent, the Subagent contacts EMANATE to inform it which objects it is managing. Figure 2-1 depicts the interaction between EMANATE, the network manager, the initialization files, and the Subagent:

Figure 2-1: EMANATE configuration

Note: EMANATE also reads a set of SNMP version 2 configuration files. See Appendix B, "SNMP Version 2 Configuration" for more information.

Setting Up EMANATE

You must perform the following tasks to set up EMANATE:

1. Set up the configuration file.

2. Define port settings.

3. Define environment variables.

The following sections describe these tasks.

Configuring EMANATE

The configuration file for EMANATE is snmpd.cnf. In snmpd.cnf, you define host variables, community access, trap specifications, and trap notifications. The installation procedure creates snmpd.cnf in the directory identified by the environment variable SR_AGT_CONF_DIR. Typically, this directory is /etc/srconf/agt, but you can use another directory if you want. If you did not install EMANATE, contact the person who did so you can locate snmpd.cnf.

As part of the product distribution, Sybase provides a generic version of snmpd.cnf. During the installation process, the SQL Server SNMP Subagent Installation Guide directs you to modify some of the entries in snmpd.cnf, but it does not describe all of the entries in snmpd.cnf.

The following sections describe the entries in snmpd.cnf and the parameters you can modify.

WARNING! Do not modify snmpd.cnf while EMANATE is running. If you do, errors may occur. If you need to modify snmpd.cnf, either shut down EMANATE first or make a copy of snmpd.cnf to modify. See "Shutting Down EMANATE" for information.

Modifying System Information

During the installation process, you are required to define three parameters that describe the host system on which EMANATE is installed. These parameters are:

• sysDescr-typically describes the host name, make, and model of the machine on which you installed EMANATE. However, you can include any other information about the host that you want.
• sysLocation-describes the physical location of the system.
• sysContact-identifies the name of the person responsible for the host and information on how to contact him or her.

The descriptions you provide for sysDescr, SysLocation, and sysContact must be less than 254 characters and are limited to one line in length. In addition, your definitions cannot end with one or more spaces. If they do, EMANATE encounters errors.

To modify host parameters, edit snmpd.cnf with any text editor and modify the parameters. The format of system variables is:

variable_name definition

where variable_name is the name of the variable and definition is the variable definition. The following example depicts valid definitions for sysDescr, sysLocation, and sysContact:

sysDescr                SQUONK, SunOS_5.4 LX workstation
sysLocation                Capitol Rm 456
sysContact                George Washington (617)555 1212

Note: sysObjectID is another host variable defined in snmpd.cnf. Unlike the other host variables, you should not modify the definition of this variable. sysObjectID is set to a value that is reserved for Sybase.

Setting Community Access

A community string is basically a password that a network manager uses to access information. Each PDU contains a community string that EMANATE uses to authenticate the privileges of the network manager. By default, snmpd.cnf defines privileges for the "public" and "private" community strings. If you want, you can modify the privileges assigned to these community strings and insert additional community specifications.

The format of a community specification is:

community com_string ip_address privs comm_id

where community is a keyword, com_string is the community string name, ip_address is the address of the machine from which requests are authorized, privs are the privileges defined for the community, and comm_id is the identification number of the community. For example, the definition:

community            public        157.135.1.2            read        4

allows the network manager on node 157.135.1.2 with "read" access when it uses the "public" community string.

When you define community specifications, be aware of the following:

• There are two possible values for privileges: read or write.
• If you want to provide access from all hosts, use the address "0.0.0.0".
• The community identifier is a feature that is reserved for future use. You should always use the number four (4) for this value.

To define community specifications:

1. Edit snmpd.cnf.

2. Locate the "Community specification" section.

3. Insert definitions for each community string on each host.

   Note: Each time you start EMANATE, it reads snmpd.cnf. If there are new community strings in snmpd.cnf, EMANATE adds the community string information to the configuration file agt.pty. See "Configuration Files" for more information.

Defining Trap Notifications

A trap is a notification that a specific event has occurred. For example, when a database becomes unavailable, the Subagent sends a trap informing EMANATE of the event. Before EMANATE can pass the trap to a network manager, you must insert a trap definition into snmpd.cnf.

The format of a trap definition is:

trap com_string ip_address

where com_string identifies the community included in the trap message, and ip_address is the address of the host machine to which EMANATE sends the trap. For example, the following definition:

trap public 135.136.1.2

directs EMANATE to send traps to the address "135.136.1.2" and include "public" in the community string.

To define trap notifications:

1. Edit snmpd.cnf.

2. Locate the "Trap community specification" section.

3. Insert trap definitions for each community string on each host.

   Note: Each community string you specify for traps must be unique; the same community string cannot appear more than once in the trap definition section. If it does, EMANATE encounters problems.

Enabling and Disabling Authentication Traps

Authentication traps are a special type of security trap. When EMANATE receives a PDU, it verifies that the community string has privileges to set or get OID information. If the community string is invalid, EMANATE sends a trap to each of the hosts defined in the trap definition section of snmpd.cnf.

By default, authentication traps are enabled. However, you can disable authentication traps by redefining the parameter snmpEnableAuthenTraps.

To disable authentication traps, set snmpEnableAuthenTraps to 2.To enable authentication traps, set snmpEnableAuthenTraps to 1. For example, the entry:

snmpEnableAuthenTraps 2

disables authentication traps.

For information on other security features, see Appendix B, "SNMP Version 2 Configuration."

Defining Ports

For EMANATE to communicate with a network manager, you must define ports for EMANATE to use.Typically, a master agent listens to port 161 for requests and returns responses and traps to port 162. However, you can configure EMANATE to use different ports.

When you start EMANATE, it determines which port to use by looking for two environment variables: SR_SNMP_TEST_PORT and SR_SNMP_TRAP_PORT. If you do not define these environment variables, EMANATE looks for port information in the /etc/services file. You use the environment variables for nonstandard port definitions and /etc/services for standard port definitions.

The following sections describe how to use standard and nonstandard ports for communication.

Note: A side effect of using nonstandard ports is that when your network manager communicates with two master agents on the same host machine, it appears as if there are two separate machines. In actuality, there is only one machine.

Defining Standard Ports

You must define ports for EMANATE to use before you start it. To define standard ports, place two entries in the file /etc/services.

To verify that ports are defined in /etc/services, enter the command:

grep snmp /etc/services

grep should display the following:

snmp            161/udp
snmp-trap            162/udp

If grep does not display the appropriate entries, edit /etc/services and put these entries in it.

Note: Because ports 161 and 162 are industry standards, you should use these ports unless they are already being used.

Defining Nonstandard Ports

In a typical SNMP environment, there is a single master agent that listens to port 161 for requests and returns responses and traps to port 162. However, in some environments, you may need to have multiple master agents. If you want, you can configure EMANATE to use nonstandard ports to communicate with network managers.

To configure EMANATE to use nonstandard ports, you must define two environment variables:

• SR_SNMP_TEST_PORT-identifies the port number for EMANATE to use for all communications other than traps.
• SR_TRAP_TEST_PORT-identifies the port number for EMANATE to use for all traps.

For example, the following c-shell commands direct EMANATE to use ports 2170 and 2171 for communication:

setenv SR_SNMP_TEST_PORT 2170
setenv SR_SNMP_TRAP_PORT 2171

Note: In addition to setting up EMANATE to use nonstandard ports, you must set up your network manager to communicate with EMANATE through these ports. See your network manager documentation or vendor for more information.

Setting Environment Variables

Before you start EMANATE, you must define two environment variables:

• SR_AGT_CONF_DIR-identifies the EMANATE configuration directory. This is the directory that contains snmpd.cnf.
• SR_MGR_CONF_DIR-identifies the EMANATE utility directory.

When you performed the Subagent and EMANATE installation, the installation procedure created directories based on your definitions of SR_AGT_CONF_DIR and SR_MGR_CONF_DIR. Sybase recommends that you set SR_AGT_CONF_DIR to /etc/srconf/agt and that you set SR_MGR_CONF_DIR to /etc/srconf/mgr. If you did not install EMANATE and the Subagent, contact the person who did to identify these directories.

To set SR_AGT_CONF_DIR, enter the following c-shell command:

setenv SR_AGT_CONF_DIR master_agent_conf_dir

where master_agent_conf_dir identifies the configuration directory. For example:

setenv SR_AGT_CONF_DIR /etc/srconf/agt

sets SR_AGT_CONF_DIR to /etc/srconf/agt.

To set SR_MGR_CONF_DIR, enter the following c-shell command:

setenv SR_MGR_CONF_DIR master_agent_util_dir

where master_agent_util_dir identifies the utility directory. For example:

setenv SR_MGR_CONF_DIR /etc/srconf/agt

sets SR_MGR_CONF_DIR to /etc/srconf/agt.

Starting EMANATE

The following sections describe what you should do before starting EMANATE, how to start EMANATE, and how to use command line options to capture messages that EMANATE generates.

Before You Start EMANATE

Before you start EMANATE, you must:

• Be "root"
• Stop any existing EMANATE master agent process
• Define communication ports
• Set the SR_AGT_CONF_DIR and SR_MGR_CONF_DIR environment variables

The following sections describe how to set user to "root" and how to shut down a master agent. See "Defining Ports" for more information on defining communication ports and "Setting Environment Variables" for information on defining EMANATE's environment variable.

Setting User to root

To start EMANATE you must be "root". You can either log in as "root" or set user to "root" with the command:

su root

Shutting Down EMANATE

To shut down EMANATE:

1. Identify the process identification number (PID) of EMANATE. 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 EMANATE process. If ps does not return a PID, EMANATE is not running.

2. Terminate the process with the command:

   kill -9 process_id

   where process_id is the PID.

Starting EMANATE

Before you start EMANATE, make sure that it is not already running. If EMANATE is already running and you try to start another EMANATE process, your request is ignored.

To start EMANATE, enter the command:

snmpdm [-aperror -apwarn -aptrace] | [-apall] 
        [-d]

where the command line arguments are:

• -aperror-enables the logging of error messages. Error messages are serious and can be potentially fatal.
• -apwarn-enables the logging of warning messages. Warning messages are nonfatal messages.
• -aptrace-enables the logging of trace messages. If you use this argument, EMANATE writes all messages to standard output. This release of the Subagent does not use the trace message capability of EMANATE. Therefore, you should never use this argument.
• -apall-enables the logging of error, warning, and trace messages. If you use this argument, EMANATE writes all messages to standard output.
• -d-redirects all messages to standard output.

By default, EMANATE starts as a daemon process. However, if you use the -aptrace, -apall, or -d arguments, EMANATE does not start as a daemon process because it uses standard output for displaying error messages. If you do not use the -aptrace, -apall, or -d arguments, EMANATE writes all messages to the log file /tmp/snmpd.log.

Note: If you have problems starting EMANATE, make sure you have performed all the tasks defined in "Before You Start EMANATE". If you are still encountering problems, see Appendix C, "Troubleshooting" for more information.

Using the Message Log

EMANATE uses the log file /tmp/snmpd.log to save messages. By default, EMANATE creates this file in the /tmp directory. However, you can direct EMANATE to create snmpd.log in another directory by using the environment variable SR_LOG_DIR.

To direct EMANATE to create snmpd.log in a different directory, define SR_DIR_LOG to the directory you want to use. For example, the command:

setenv SR_LOG_DIR /tmp/snmp

directs EMANATE to create snmpd.log in the /tmp/snmp directory.

Starting EMANATE at Boot Time

Sybase recommends that you automatically start EMANATE when you start your system. You can do this by putting the EMANATE 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.