Support Through SAS

SNMP Applet Server (SAS) allows the applet to send and receive SNMP packets to any managed device on the network. SAS provides communication for applets that are unable to connect directly to managed devices due to security limits. The SNMP requests made from the applet are passed onto SAS through TCP connection. SAS uses UDP to connect to the managed device and perform SNMP operations and pass the response back to the applet through TCP.

Similarly, if the applet wants to receive traps from the agent, it can register with SAS with the port on which it wants to listen for traps. The SAS opens a socket and listens for traps on that particular port on behalf of the applet and passes the traps to the applet.

Apart from these, SAS can also be used for file operations, such as creating a new directory, deleting an existing directory, creating a new file, appending to an existing file, and deleting a file.

From an applet, loading MIBs from a database and saving v3 information to a database is not possible if the database and the webserver are on different hosts. However, these are supported from applets in the AdventNet SNMP API by using SAS. All the database queries from the applet are forwarded to SAS. SAS queries the database to get the results and passes on the results to the applet.

SAS can either be started as a standalone application or part of any other application. The SAS application can be started by giving the following command.

SAS is started at any random port and the port number is written to the SASPort.html file. The applet client reads this file to get the port number in which SAS is running and establishes communication to perform SNMP operations.

The start_server.sh/bat file present in the <bin> directory of the package starts SAS and the web server. The following options can be given as command line arguments to the SAS application.

"SAServer [-D] [-p port] [-d applet_directory] [-webserver_root directory] [-restrict_sockets] [-session_client class] [-log_class class] [-register_client class] [-usewebserverashost] [-driver DBdriverName] [-url DBurl] [-user DBuserName] [-pass DBpassword] [-portfile filename]" where

• The -D option enables the debug and prints the packet dumps.

• -p port - specifies the port in which SAS can start. It writes the port number to the SASPort.html file.

• -d applet_directory - specifies the directory in which the SASPort.html file is written. By default, it is the current directory. The SASUsers subdirectory, which is used to save data from the applets, should be created under the directory specified.

• -webserver_root directory - specifies the root directory of the web server.

• -restrict_sockets - allows socket access only to SNMP UDP ports 161 and 162.

• -server_client class, session_client class, log_class class - implement SAServerClient, SASessionClient, and SASLogInterface interfaces.

• -register_client class- sets the user's implementation of the RegisterClient interface. This interface can be used by the API users to receive the traps from different agents. Whenever the SASClient calls the method reqTraps(int), (Refer "Provides a mechanism to receive traps" given below) the registerForPort(int, SocketListener) method of RegisterClient is called where SocketListener is equivalent to SASClient). The API users can write their own implementation for receiving traps and can notify the received traps to the API by calling the receivedData(ProtocolDataUnit) method of SocketListener interface. The API users should not implement the "SocketListener" interface. This is implemented by the SASession class.

• -usewebserverashost - handles the webserver host. When this is set to true, if the host is specified as "localhost" and a SNMP query is made, the query is sent to the machine where the client is running.

• -driver DBdriverName, -url DBurl, -user DBuserName, -pass DBpassword, - specify the database parameters. If the database connection is established in the server, all the clients can access the same database.

• -portfile filename - specifies the filename while starting the SAServer. On the client side, the tag should be given as PORT_FILE_NAME and the corresponding value as the filename. The method setPortFileName(String filename) in the SAServer class enables the user to configure the filename for storing the port value in which SAS has been added. The default filename is SASPort.html.

SAS can also be integrated with other applications so that it can be started as part of that application. To start the SAS from other applications, the user has to instantiate SAServer, initialize necessary variables and start the SAServer thread.

First we need to instantiate the SAServer. Following are the two constructors provided by the SAServer class.

Here, server_client and session_client implements SAServerClient and SASessionClient respectively. They can be null, which is equivalent to the default constructor. The following command starts the SAServer thread.

The following command closes SAServer.

Using the SAS server, the applet support API offers the following services to the applets built on top of the low-level API.

• Provides ability to access SNMP data available with the devices in the network.

• Provides a mechanism to receive traps.

• Provides ability to create/delete files and directories and save information on files on the server.

• Facilitates sending and receiving application-specific data.

• Facilitates execution of custom Java classes on the server and getting the results.

• Provides ability to resolve between internet hostnames and addresses.

• Provides ability to access databases.

We will look at each of the above feature and see how the API supports them and how to use them in applications.

Provides ability to access SNMP data available with the devices in the network

The SASClient class provides a means for applets to transparently talk to SNMP devices, through the SAS server, getting around the security restrictions. Applets do not have to instantiate this class explicitly. When SnmpSession is opened, it instantiates a SASClient for communicating with the SAS server. It is explained in the following piece of code.

The session.open(Applet) method instantiates the SASClient. The SASClient constructor, depending on the value set in the setSASProtocol() or from the applet parameter in the HTML file, chooses the protocol it wants to communicate. The value of the protocol can be either TCP_PROTOCOL (1) or HTTP_PROTOCOL (2). TCP_PROTOCOL uses TCP/IP connection and forward the SNMP request to SAS while HTTP_PROTOCOL uses HTTP protocol and forward the request to the servlet loaded with the web server. By default, the value of the protocol is 1 (TCP/IP).

The SASClient constructor reads SASPort.html file from the applet directory to get the port on which the SAS server is available. If the SASPort.html file is available in some other directory, it is specified in the applet HTML file by the SAS_PORT_DIR applet parameter. A TCP connection is established between the applet and the SAS server running on the port.

When applets wish to interact with SNMP devices, they simply fill in the agent host, port, etc. in the SnmpPDU and send them over the session.

From the above code, it is evident that except during instantiating the SnmpSession object, applets are identical to applications. It is left to the SnmpSession object to know whether it is running in application or applet context. The SnmpSession object uses SASClient to communicate with the devices through the SAS server when it runs in applet context. Note that the SAS server can support multiple applet clients at the same time where each applet can be requesting to different devices on the network.

Moreover, access to arbitrary UDP ports from the applet clients can be restricted using the restrict_sockets option available with the SAS server. This disables all but the SNMP UDP ports 161 and 162. By default, applet clients can send and receive data to any UDP port through the SAS server and request the SAS server to listen on any port for traps.

Provides a mechanism to receive traps

If applets wish to receive traps and notifications, they have to register with the SAS server. During registration, applets can specify the port on which the SAS server should listen for traps. The following piece of code illustrates how applets request the SAS server to deliver traps.

Applets get a reference to the SASClient class used by the session using the getSASClient() method available in SnmpSession. Note that more than one applet can request the SAS server to deliver traps on the same port.

When a request to forward traps on a given port is received by the SAS server, it starts listening on the port for traps.

In order to receive the traps from the SAS server, applets should either implement the SnmpClient interface or poll for traps using checkResponse(). It is always best for applets to implement the callback() method in SnmpClient because it saves the overhead of polling using checkResponses(). The following piece of code illustrates this.

Provides ability to create/delete files and directories and save information on files on the server

Applets developed using AdventNet SNMP API can create and delete directories in addition to reading and writing into files in the web server. Applets can only perform these operations on directories and files available in the SASusers subdirectory in which SASPort.html was created by the SAS server. The SASusers directory must exist for the applet to perform these operations and the location of this directory can be specified using the -d option while starting the SAS server. The default location of the SASUsers directory is the directory from which the SAS server is started.

The following methods are available in the SASClient class to perform file operations.

Note that the file operations available with the SAS server can be disabled. If the SAS server is started with the -no_file_output option, the SAS server does not allow file operations from applet clients. Also, the directory in which the file operations are allowed can be specified using the -d option.

Facilitates sending and receiving application-specific data

Applets can send their own data to server side application through the SAS server. The SAS server provides the SASessionClient interface for this purpose. Server side applications should implement the SASessionClient interface and register it with SAS server using the -session_client option available with the SAServer.

The userSyncSend() method available in SASClient is used by applets to send data to server side applications. The following code illustrates how applets send their own data.

Here, requestType is greater than SASClient.SAS_VALID_TYPES, requestData can be any data sent by the applet client, and responseData is the response returned by the server side application. The SASClient and the SAS server pass the request and the response transparently between the applet and the userCall() method available with the SASessionClient interface.

Note that only one class that implement SASessionClient can be registered with the SAS server for all applet clients and a new instance of SASessionClient class is instantiated for every applet client that connects to the SAS server.

Facilitates execution of custom Java classes on the server and getting the results

Applets can invoke methods on the SAS server using the clientCall() method available with the SASClient class. This method can be used to build application-specific functions around SAS by extending the interaction between the applet client and the SAS server. enables applet clients invokes a method in the server by using the following code.

On the SAServer side, the clientCall() method is available in SAServerClient and SASessionClientinterfaces. If both interfaces are available, the SAS server calls the SAServerClient interface method first and then calls the SASessionClient method. The SAServerClient class is registered using the -server_client option and the SASessionClient class is registered using the -session_client option while starting the SAS server.

Note that there is only one instance of the SAServerClient class for a SAS server while there is one instance of SASessionClient for each applet client. Therefore, server side applications that require to maintain client-specific information should implement the SASessionClient interface.

Provides ability to resolve between internet hostnames and addresses

Applets can use getHostAddress() and the getHostName() methods available in SASClient class to map between IP address and hostnames. The getHostAddress() method resolves the host name to a dotted IP address with the help of the SAS server. The getHostName() method maps the dotted IP address to a fully qualified internet host name. pplets use these methods as follows.

Provides ability to access databases

The following four methods are provided in SASClient to access the database.

1. connectDB(String driver, String url, String user, String password)
   
   This method is to set up the database connection. The jars or class files necessary for accessing database should be included in the CLASSPATH on the server side and not to be downloaded from the server. If the specified driver class is not present, this method throws an exception ClassNotFoundException. If the database connection with the specified url, user, and password is not established, an SQLException is thrown.

2. closeDB()
   
   This method is to close the database connection. It throws an SQLException if the database connection cannot be closed.

3. queryDB(String queryString)
   
   This method is to query the specified database. The user should pass the SQL query string as argument. The method returns an instance of ResultSet. Currently, the database tables with all the columns of type "varchar" or "text" can only be queried. This method is equivalent to the "executeQuery(String)" method of "java.sql.Statement" class. It throws an SQLException if a database access error occurs.

4. updateDB(String updateString)
   
   This method is to update the database with new values, deleting a row, inserting a row, etc. This method is equivalent to the "executeUpdate(String)" method of "java.sql.Statement" class. It throws an SQLException if a database access error occurs.