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:
-
Sending an email message
-
Posting a news article to one or more newsgroups
-
Performing an HTTP operation to post to a URL or to get a URL (advanced
options only)
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:
-
On a specified date and time
-
At recurring time (for example, every Tuesday at 10 a.m.)
-
At periodic intervals (for example, every five hours)
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:
-
A document is changed, moved, copied, or deleted
-
Someone views or modifies a document attribute
-
A document is locked or unlocked
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:
-
A directory is changed, moved, copied, or deleted
-
A directory is added
-
Someone lists a directory
-
Someone views or modifies a directory attribute
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:
-
Check the server at 5 a.m. every Monday morning for all documents that
have been modified in the preceding week.
-
Check the server at 5 a.m. every Monday morning for all documents that
contain the string "JavaScript" that have been modified in the preceding
week.
-
Check the server at 5 a.m. on the first of each month for all new documents
with the word Netscape in their title.
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:
-
From the Server Manager, choose Agents & Search.
-
Click the Agent Management link.
-
Click the Yes radio button under the Enable Agent Services label.
-
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.
-
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.
-
Type in the maximum number of agents an individual user can have. The number
you specify must be an integer greater than 0.
-
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.
-
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.
-
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.
-
Type in the name of your organization. This identifies the organization
associated with this server.
-
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.
-
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.
-
ns_agent_base.idx is an index to the main agent database. It provides
the other index files with quick access to the agent database.
-
ns_agent_user.idx provides the server with a quick way to find
agents based on username. (Essentially, this file contains usernames and
pointers to locations in the main database file. Given a username, the
server can use this index file to "look up" that user's agents in the main
database file.)
-
ns_agent_class.idx provides the server with a quick way to find
agents based on class (or type). (This file contains classes and pointers
to locations in the main database file. Given a class, the server can use
this index file to "look up" agents of that class in the main database
file.)
Fixing inconsistencies and file corruption
The set of files that store agent information are
in one of the following three states:
-
Valid (nothing is wrong with the files)
-
Inconsistent (the index files are not in sync with the main database file)
-
Corrupted (the main database file has become corrupted)
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/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:
-
Begin by shutting down your web server.
-
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/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:
-
Begin by shutting down your web server.
-
On the command line, type in this command:
agent_salvage filePathname/filePrefix
filePathname/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
server_root/https-yourServer/agents-db/ 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:.
-
In the Web Publisher applet window, from the Services menu, choose Agent
Services to go to the agent services page.
-
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.