Using agents


etscape Enterprise Server allows you to use server-based agents to manage server files and folders. Agents act as watchdogs for you, watching for a specific event or time, and then performing a task for you. For example, you could set up a document agent to notify you when a specific URL has been updated, or you could have a search agent execute every week at the same time to pull a list of all web publishing documents that have been updated during the week. The notification could be an email message or a posting to a newsgroup.

An agent is stored on the server, so you must be connected to the server when you create the agent. The agent resides on the server until it is deleted or completes the assigned task. The server only allows users with the correct permissions, as recorded on the access control list (ACL), to submit an agent. An agent can only perform operations that you are authorized to perform, but it cannot access authenticated sites because agents don't send authorization data with their requests.

As server administrator, you can configure how your server manages agents. For example, you can define who has access to specific agent events and you can restrict who can create or disable agents.

One of the options you have as server administrator is to turn web publishing off. When you do so, all agents for the server are also turned off and clients cannot use Netscape Web Publisher to access agent services. When you turn web publishing back on, agents that were turned off because you turned off web publishing are also turned back on. Agents that were disabled for other reasons are still disabled.

Note
Because agents are stored on the server, you must have sufficient disk space available for all agents created on your server. A general rule of thumb is to allow 512 bytes per agent, which calculates out to approximately 70-100MB of space for 100,000 agents.

Types of agents

There are several types of agents, each of which has a particular use. When an event occurs that an agent is monitoring or when the specified time for activation occurs, the agent activates and begins to perform its assigned actions, such as:

Timer agents

Timer agents respond to time-related events that occur as a result of the date or time. You can submit an agent to activate:

Document agents

Document agents respond to document-related events that take place when something has occurred to a document on the server. Some examples are:

Directory agents

Directory agents respond to directory-related events that take place when something has occurred to a directory on the server. Some examples are:

Search agents

Search agents execute periodically, notifying the client of any documents that have been modified since the last time the search agent executed. Search agents can also check the content of documents, pulling a list of all documents in the chosen collection that contain the specified search criteria or text string. You can limit the content search to recently modified documents or you can extend the search to include all server documents. Some examples of search agent tasks are:

Creating authorized users

Only users that you have added to an access-control database are permitted to use agents. You must use the Administration Server to add users and groups.

Agents access the ACL database that is the default for your server. The local LDAP database is typically set as your default during server installation, but you can direct agent services to access a different ACL database. See Chapter 6, "Controlling access to your server" for more information about setting access control.

Configuring agent services

As server administrator, you must begin by enabling and configuring agent services. You can enable or disable agent services as well as define many default characteristics of individual agents.

Note
Before you can use agent services on your server, you must define the MTA (mail) and NNTP (news) hosts for your server. To do this, use the Server Manager for your Enterprise Server. Use the Server Preferences|Network Settings link and enter values for the MTA Host and NNTP Host fields.
To set up agent services for your server, follow these steps:

  1. From the Server Manager, choose Agents & Search.
  2. Click the Agent Management link.
  3. Click the Yes radio button under the Enable Agent Services label.
  4. Type in the full path of the agent directory in the Agent Directory field. This is where files containing information about agents are kept. The default is server_root/https-yourServer/agents-db. If you want to specify a different directory, make sure you include a full path.
    Note: The agent directory must be owned by the same user as the server user. That is, if the server is not running as root, the server user, typically "nobody," must be the user who owns the agent directory.
  5. Type in the maximum number of agents for all users that are allowed on your server. The number you specify must be an integer greater than 0.
  6. Type in the maximum number of agents an individual user can have. The number you specify must be an integer greater than 0.
  7. Type in the maximum number of days any agent can exist. The number you specify must be an integer greater than 0. This provides a calculated expiration date for your agents. Clients cannot input a longer agent life for a particular agent.
  8. Type in the maximum times an agent can be activated. The number you specify must be an integer greater than 0. Clients cannot input a larger amount of activations for a particular agent.
  9. Type in the agent's server administrator's email address. This is the "From" address included on any emails that are sent from the server. This can also be used to identify agents that encounter error conditions.
  10. Type in the name of your organization. This identifies the organization associated with this server.
  11. Type in the minimum timer resolution, in minutes. This must be an integer and must be greater than or equal to 5. This limits the period that clients can input as the interval at which periodic timer agents can activate.
  12. Click OK to apply your changes.

Agent information in the configuration files

There are several configuration files that govern how agent services operate. In general, you don't access these files, but this section briefly introduces them just in case you do need to know something about them.

The system configuration file is mapped to the agent_system.ini file in the obj.conf file. This defines your system and data directories.

This in turn points to the agent_string.ini file that contains the text strings that are used to create the HTML agent services forms.

The information that you enter through the Agents & Search |Agent Management form (See "Configuring agent services" for more information), is reflected in the agent.conf file.

The access control list (ACL) data is configured in the magnus.conf file, which points to another file, server_root/httpacl/generated.https-yourServer.acl.

Recovering agent files

Agent information is stored in a set of database files on the server. It is possible for the data in these files to become inconsistent or corrupted. If this happens, you can use the command-line utilities (provided with the web server) to salvage and recover agent information from the corrupted files.

The next sections explain how agent information is stored and how to recover this information if file corruption occurs.

How agent information is stored

Agent information is stored in this database file: server_root/https-yourServer/agents-db/ns-agent-base

In order to provide quicker access to information in this file, the web server also creates and uses three index files.

Fixing inconsistencies and file corruption

The set of files that store agent information are in one of the following three states:

If the files are in the "Inconsistent" state, you need to run the agent_repair command-line utility to fix the index files. For details, see "Recovering from inconsistencies" on page 236.

If the files are in the "Corrupted" state, you need to run the agent_salvage command-line utility to recover the data. For details, see "Recovering from file corruption" on page 236.

Figure 12.1 illustrates these different states and the utilities that you need to use to return the files to a "Valid" state.

Possible states of the files storing agent information

Recovering from inconsistencies

In some cases, the index files develop inconsistencies and the server cannot be able use them to find entries in the main database file (ns_agent_base). When this situation occurs, the message "Agents database has become internally inconsistent" is logged to the agent.log file, and the server displays the following error message:

	Agent store files are out of sync
Because both index files consist of data that is already stored in the main database file, you can recover the index files from the data in the main database file.

To recover the index files, run the agent_repair.exe utility, which is located in the server_root/Netscape/SuiteSpot/plugins/agents/bin directory. Unlike with corrupted files, inconsistent files are repaired in place, with the "new" files overwriting the original files.

To run this utility:

  1. Begin by shutting down your web server.
  2. On the command line, type in this command:
    	agent_repair filePathname/filePrefix
    
    filePathname is the pathname for the agent file directory. The default is server_root/https-yourServer/agents-db.

    filePrefix is the prefix that is common to the names of the database and index files. Typically, this prefix is ns_agent.

For example, you would execute a command similar to the following command:

agent_repair server_root/https-yourServer/agents-db/ns_agent

Recovering from file corruption

In some cases, the main database file (ns_agent_base) might get corrupted. When this situation occurs, the server displays the following error message:

Agent store files are corrupted

The message "Agents database has become corrupted" is logged to the agent.log file. You can change this message by changing the text in the agent_strings.ini file. If you do so, the new message appears instead of this standard one.

If this happens, you need to recover the data from the main database file. (Unlike the problem with inconsistent indexes, corruption in the main database file may result in data loss.)

To recover the data, run the agent_salvage.exe utility, which is located in the server_root/Netscape/SuiteSpot/plugins/agents/bin directory. This utility retrieves data from the corrupted files and creates new files for the data. Unlike with inconsistent files, corrupted files cannot be repaired in place, so new files are created in addition to the original files rather than overwriting them.

To run this utility:

  1. Begin by shutting down your web server.
  2. On the command line, type in this command:
    agent_salvage filePathname/filePrefix newFilePrefix

filePathname is the pathname for the agent file directory. The default is server_root/https-yourServer/agents-db.

filePrefix is the prefix that is common to the names of the database and index files. Typically, this prefix is ns_agent.

newFilePrefix is a prefix that you assign to the newly created files that contain the recovered data.Typically, this prefix is ns_agent_recovered.

For example, suppose you run the following command:

agent_salvage server_root/https-yourServer/agents-db/ ns_agent ns_agent_recovered

The agent_salvage utility retrieves data from the following corrupted files:

ns_agent_base

ns_agent_user.idx

ns_agent_class.idx

The utility then creates the following new files in the same directory as the original files and saves the data to these files:

ns_agent_recovered_base

ns_agent_recovered_user.idx

ns_agent_recovered_class.idx

The utility also displays the following message to the user console when it is finished:

Agents database has been repaired

Accessing agent services

There are two ways to access the agent services user interface: you can go directly through the server or through Netscape Web Publisher.

To access agent services through the server, type in the following URL:

http://yourServer/agents
To access agent services through Web Publisher, you can either of these methods:.

  1. In the Web Publisher applet window, from the Services menu, choose Agent Services to go to the agent services page.
  2. From the Netscape Web Publisher Services window, click the Agents link.

The Netscape Enterprise Server Agent Services page appears. The lower left frame contains the links you need to create and view agents. The lower right frame describes agent services and will be used to display information about a specific agent once you have selected one.

For further information, see the Web Publisher User's Guide, which is available through the online help system in user component such as agent services, search, and Web Publisher. To access help information, you can use the Help menu command in Web Publisher, or you can click the Help button on the Agent Services page, on the Web Publisher Services page, or on any of the search interface forms.


Copyright 1997 Netscape Communications Corporation. All rights reserved.