Chapter 1   Introducing the iPlanet Partner Agent for ECXpert Server

This chapter decribes the iPlanet Partner Agent for ECXpert client/server system and the features of the Partner Agent Server in particular.

The following topics are discussed in this section:

• The Partner Agent for ECXpert Client/Server System



• Partner Agent Server Features



• Partner Agent Server Distribution



• Pre-configured Settings for Interaction with ECXpert



• Starting Partner Agent Server



• Stopping Partner Agent Server

The Partner Agent for ECXpert Client/Server System

---

Partner Agent for ECXpert is a client/server solution for secure file transfer and automated document processing. Partner Agent products work with the ECXpert system to provide high performance file transfer capabilities as well as state of the art security, reliability, and automation. Partner Agent is fully compatible with FTP and HTTP(S) standards.

Partner Agent is made up of the Partner Agent Server and the Partner Agent Client. Partner Agent Server is integrated with ECXpert, turning ECXpert into a secure file transfer site. Partner Agent Client runs as a stand-alone application that turns your PC into a powerful, secure, and reliable download and upload manager for exchanging files with ECXpert, as well as with other machines.

Partner Agent Server allows Client users to exchange files directly with ECXpert. Partner Agent Server uses the ECXpert submit utility to upload files from the Client to ECXpert, where they are processed further as required. It uses the ECXpert poll utility to retrieve files downloaded from ECXpert; these files can be viewed and processed using the Client.

Partner Agent is scalable, making it an ideal building block for industrial-strength extranet applications.

Partner Agent Server

Partner Agent for ECXpert Server is a customized, pre-configured system that allows you to turn ECXpert into a secure file transfer site.

In addition to integrating state-of-the-art security standards, such as Secure Socket Layer (SSL) and digital certificates (X.509), Partner Agent Server contains a sophisticated access control system as well as EnGuard^TM security auditing software that automatically warns of potential security issues.

Partner Agent Server also guarantees Extranet data delivery and data integrity while protecting corporate bandwidth.

Partner Agent Server's functionality is extended through a plug-in architecture that uses ActiveAgents. ActiveAgents are transactional software agents that call ECXpert APIs to initiate events based on file transfers and to also feed information into back-end applications, such as databases, enterprise scheduling software, and network printing operations. ActiveAgents also make it easy to add third-party functionality to Partner Agent Server, such as virus scanning, file format conversion, or additional security mechanisms as required.

Partner Agent Server comes with a browser-based administration system, which can optionally be used to reconfigure the Server in special circumstances; it is not needed in most cases since the Server is already preconfigured for optimal, secure performance with ECXpert. It also comes with a secure command line client, which can optionally be used for testing the system.

Partner Agent Client

Partner Agent Client software for Windows 98/95 and NT provides high-performance, reliable, and secure file transfer of critical business documents between your Windows desktop and ECXpert or other machines—over your intranet, business extranet, or the Internet.

You can also use a standard browser as a client for file transfers to non-ECXpert machines.

Partner Agent Server Features

---

• Pre-configured settings for interaction with ECXpert



• Full compatibility with the FTP standard (RFC 959).



• Secure Sockets Layer (SSL) encryption.



• Logging of all server activity.



• Graphical and tabular server activity analysis.



• Extended FTP commands support mirror servers.



• Optional web-based server administration GUI.



• Real-time server activity monitor.



• Server access restrictions.



• ActiveAgents architecture for dynamic server applications.



• Virtual user capabilities for secure virtual accounts.



• EnGuard^TM security auditing system with heuristic break-in analysis.

Partner Agent Server Distribution

---

The Partner Agent Server distribution is installed under the $NSBASE/NS-apps/paserver directory.

Partner Agent Server Programs and Scripts

The following programs are provided in the $NSBASE/NS-apps/ECXpert/bin directory.

ECXpert Wrapper

ecxpa-m-server.

This is an ECXpert administrative wrapper around the Partner Agent servers. The Partner Agent Server has an entry ([ecxpa-server]) in the ECXpert ecx.ini file just like any other ECXpert server, which means it can be stopped and started via the ECXpert administrative user interface just like any other ECXpert server. When this server is started, it in turn starts all the Partner Agent servers. When the ECXPA server is stopped, it in turn stops the Partner Agent servers. This feature means that a uniform administrative interface is provided for all ECXpert servers.

ECXpert ActiveAgents

The following scripts and programs, invoked via Partner Agent Server file transfers, provide interaction between Partner Agent Server and ECXpert.

ecxpa-welcome.

This is a shell script invoked when a user attempts to login to the Partner Agent Server. A welcome message is relayed to the client program and displayed to the user.

ecxpa-bye.

This is a shell script invoked when a user logs out of the Partner Agent Server. A message is relayed to the client program and displayed to the user.

ecxpa-fd-certify.

This is a shell script invoked when a user presents a certificate to the Partner Agent Server, which has been configured to expect one, for authentication.

ecxpa.

This is a shell script wrapper around an ECXpert ActiveAgent. The wrapper establishes an environment that will allow the subsequent program invocation to execute in a well-defined manner. The program to be invoked, together with any arguments it may take, is passed to the shell script wrapper on the command line. The remaining programs listed below are all invoked by the ecxpa script. Each of these wrapped programs follows the standard ECXpert convention of taking the location of the ECXpert ecx.ini file and the server section name as command-line arguments. This mechanism provides an extensible and consistent way to pass parameters into these programs. The ecx.ini file section name is [ecxpa-server]. For example, for this release the value of debug_flag is examined by each of these programs and an ECXpert debug log is produced (under the $NSBASE/NS-apps/ECXpert/data/logs directory, as usual) if it is enabled.

ecxpa-config.

This program returns information about the ECX member that is essential for correct subsequent file transfer. It includes the ECXpert member's home directory location as well as the UNIX userid and groupid by which to execute the ActiveAgent programs.

ecxpa-login.

This program authenticates the ECXpert member name and password supplied against the ECXpert member database/directory.

ecxpa-submit.

This program is invoked at the completion of a file upload from the Partner Agent client. It uses ECXpert APIs to submit the uploaded file to ECXpert. From the client user's perspective, this is an atomic one-step process. A file upload from the remote client is essentially a direct submission to a remote ECXpert system.

ecxpa-retrieve.

This program is invoked at the beginning of a file download from the Partner Agent client. It uses ECXpert APIs to retrieve the specified file from ECXpert. From the client user's perspective, this is an atomic one-step process. A file download request from the remote client is essentially a direct poll of a file from the remote ECXpert system. It uses the poll interface and is therefore subject to the same limitations that poll has.

ecxpa-cleanup.

This program is triggered at the end of a file download. Depending on the outcome of the file download, it will report back to the ECXpert tracking log whether or not the file download was successful. It also removes any temporary files created during the file download.

Partner Agent Server Libraries

To support these executables, the following shared libraries are supplied in the $NSBASE/NS-apps/ECXpert/lib directory:

• libecxpacleanup10.so



• libecxpaconfig10.so



• libecxpalogin10.so



• libecxpaplugin10.so



• libecxparetrieve10.so



• libecxpaserver10.so



• libecxpasubmit10.so



• libecxpautil10.so

Partner Agent Server Section of the ecx.ini File

The Partner Agent Server installation script automatically adds a a new section, [ecxpa-server], to the ECXpert ecx.ini file in the $NSBASE/NS-apps/ECXpert/config/ directory. Table 1 outlines the parameters in this section.

Table 1-1    [ecxpa-server] section of the ecx.ini file 

Entry	Description
Parameters that should not be changed
server_type	Type of server. All servers (section_type = server) sharing same server_type value are treated as multiple instances of same server. Default: 19; do not change.
snmp_trap_flag	Trap information for SNMP service? Restrictions—valid values: yes, no Default: yes
snmp_trap_level	SNMP event level to trap. Restrictions—valid values: - 0 = all messages - 10 = information, warning, and error messages - 20 = warning and error messages - 30 = error messages only Default: 10
section_type	Type of section. Default: server; do not change.
protocol_id	Protocol identifier. Default: 775
port_location	Location to pick up the port. Default: mmap
listener_level	Listener level. Number of listener threads to launch on startup. Default: 1; do not change.
listener_type	Listener type. Restrictions—valid values: - dynamic = Administrative Server assigns - manual = always use value in listener_port Default: thread
max_listeners	Maximum number of listener threads that are allowed. Base on concurrent processing needs, if multiple submission units are to be processed in parallel. Restrictions: Total number of threads you specify must be supported by your hardware. Default: 4
runnable_flag	Can executable be run? Restrictions—valid values: - yes = executable will be run as needed - no = executable will not be run (e.g., test situation) Default: yes
thread_mode	Thread operational mode Restrictions—valid values: - threaded = run threaded - serialized = run serialized Default: threaded (only the Admin. server should be serialized; in all other sections where section_type= server, it is strongly recommended that you leave this setting as threaded)
listener_time_out	Listener timeout, in seconds. Default: 10
admin_time_out	Admin server time out period, in seconds. Default: 10
start_mode	Server start mode. Restrictions—valid values: commandline, background Default: background
type	Type of executable. Restrictions—valid values: none, daemon, process Default: daemon
Machine independent information
host_name	IP address of host machine where instances of executable are run. Restrictions: Must be a valid IP address in your domain. Default: set during installation
File and directory information
exec_path	Executable path. Full path to the executable. Default: $NSBASE/NS-apps/ECXpert/bin/ecxpa-m-server
Multi-threading parameters—do not change
max_thread_flag	Limit the number of threads running in system? Restrictions—valid values: yes, no Default: yes; do not change.
worker_max_threads	Number of worker threads to run in parallel. Default: 4; do not change.
master_max_threads	Number of master threads to run in parallel. Default: 4; do not change.
master_max_threads_queued_flag	Queue master threads above master_max_threads? Restrictions—valid values: yes, no Default: yes; do not change.
master_max_threads_queued	Maximum number of master threads to queue. Default: 500; do not change.
master_max_threads_stacked	Maximum number of master threads to place on stack. Default: 500; do not change.
Port information
listener_port	Listener port number. Restrictions: Ports used by ECXpert must not be used by other applications. Default: set during installation
admin_port_type	Administrative port type. Restrictions—valid values: - dynamic = Administrative Server assigns - manual = always use value in admin_port Default: dynamic
listener_port_type	Listener port type. Only set when adding your own network_id. Restrictions—valid values: - dynamic = Administrative Server assigns - manual = always use value in admin_port Default: dynamic
admin_port	Administrative port number. Restrictions: Ports used by ECXpert must not be used by other applications. Default: set during installation
Start and stop scripts
pa_server_start_admin	Program that starts the HTTPS admin server, which provides a browser-based user interface to configure the installation, from the command line. Spawned when the server is started. Default: $NSBASE/NS-apps/paserver/bin/start_admin
pa_server_start_agentd	Program that starts the agent server, which runs the ActiveAgent programs that perform the back-end ECXpert interactions, from the command line. Spawned when the server is started. Default: $NSBASE/NS-apps/paserver/bin/start_agentd
pa_server_start_httpd	Program that starts the HTTP server from the command line. Spawned when the server is started. Default: $NSBASE/NS-apps/paserver/bin/start_httpd
pa_server_start_ftpd	Program that starts the ftp server from the command line. Spawned when the server is started. Default: $$NSBASE/NS-apps/paserver/bin/start_ftpd
pa_server_stop_admin	Program that stops the HTTPS admin server, which provides a browser-based user interface to configure the installation, from the command line. Spawned when the server is shut down. Default: $NSBASE/NS-apps/paserver/bin/stop_admin
pa_server_stop_agentd	Program that stops the agent server, which runs the ActiveAgent programs that perform the back-end ECXpert interactions, from the command line. Spawned when the server is shut down. Default: $NSBASE/NS-apps/paserver/bin/stop_agentd
pa_server_stop_httpd	Program that stops the HTTP server from the command line. Spawned when the server is shut down. Default: $NSBASE/NS-apps/paserver/bin/stop_httpd
pa_server_stop_ftpd	Program that stops the ftp server from the command line. Spawned when the server is shut down. Default: $NSBASE/NS-apps/paserver/bin/stop_ftpd
Configurable options
autostart_flag	Start this process automatically when the ECXpert Administrative Server is started? Restrictions—valid values: yes, no Default: no
restart_flag	Restart this executable automatically if it experiences an abnormal exit? Restrictions—valid values: - yes = automatically restart when ECXpert is restarted - (you are confident manual intervention is not required) - no = do not restart when ECXpert is restarted - (you expect that manual intervention may be required) Default: no
Debug output configuration
stderr_path	Fully specified path for log file to receive standard output from low level trace. Default: $NSBASE/NS-apps/ECXpert/data/log/ ECXpert.log.ecxpa-server.dat
stdout_path	Fully specified path for log file to receive standard output from low level trace. Default: $NSBASE/NS-apps/ECXpert/data/log/ ECXpert.log.ecxpa-server.dat
debug_flag	Turn on low level tracing information? Restrictions—valid values: yes, no Default: no

New MSGFORMATS Messages in Database

The Partner Agent Server installation process updates the MSGFORMATS table in the database to include seven new messages.

ECXpert Member Directories

The Partner Agent Server installation process creates new home directories for each existing ECXpert member under the $NSBASE/NS-apps/ECXpert/data/pas directory.

Pre-configured Settings for Interaction with ECXpert

---

Partner Agent Server is installed with default configuration settings that ensure optimal, secure performance with ECXpert. These defaults enable fast ramping and deployment. Use of the browser-based Administration System to modify the settings is, in most cases, neither required nor recommended.

Some of the default configuration settings are outlined in this section.

Default Administrator Username and Password

The default username and password for accessing the optional browser-based Administration System are ECX and ECX.

For more information about the browser-based Administration System, see Part 2, "(Optional) Using the Server Administration System".

Default Signing Certificate Password

The default password for signing certificates, for which you are prompted whenever you run the gencerts utility, is ECXpert.

For more information about the gencerts utility, see "gencerts—Generating Self-issued Certificates".

Default ActiveAgents

ActiveAgents are programs, triggered by user activity on the Partner Agent Server, that interact with the ECXpert server. They handle ECXpert member authentication programs as well as file submission and retrieval.

Figure 1-1 shows the default ActiveAgents.

Figure 1-1    Default ActiveAgents

Default Security Settings

By default, Partner Agent Server has been pre-configured for maximum security. Data passing over the connection between the Partner Agent Client and the Partner Agent Server is encrypted via Secure Socket Layer (SSL). Client users also must present a valid certificate to the server for authentication.

After a user's certificate has been authenticated, Partner Agent Server extracts the username from the Distinguished Name (DN) string and prompts for a password. This username/password combination must correspond to a valid ECXpert member. As pre-configured, the Server authenticates users only via the ActiveAgent for ECXpert authentication, ecxpas-login, which calls ECXpert APIs to perform this authentication against the ECXpert member directory/database.

Figure 1-2 shows the default SSL settings. The default user authentication settings are shown in Figure 1-3.

Figure 1-2    Default Secure Socket Layer Settings

Figure 1-3    Default User Authentication Settings

Starting Partner Agent Server

---

To start the Partner Agent Server:

1. Enter the ECXpert URL in your browser.




Enter the following URL in your browser:



http://<hostname>:<port>/



where <hostname> is the name of the host machine where ECXpert is installed, and <port> is the port number ECXpert is using.



The ECXpert home page (Figure 1-4) is displayed.

Figure 1-4    ECXpert home page

2. Click the Admin link. The initial screen for the Server Administrative Interface is displayed. If the ECXpert Administrative Server is running, the Management tab appears as shown in Figure 1-5.

Figure 1-5    Initial Server Administrative Interface screen (ECXpert Administration Server is On)

3. Toggle the PA Server switch to the On position.



4. Click the Update Screen button after ten seconds has passed.




The screen is updated to reflect the change you just made.

When the Partner Agent Server is started, the following servers are started:

admin.

This is the Partner Agent administrative HTTPS server that provides a browser-based user interface to configure the Partner Agent Server installation. The ECXpert user is provided with a pre-configured package that minimizes use of this administrative interface (see "(Optional) Using the Administration System"). The Partner Agent Server system can be configured and administered from a remote browser where the communication between the browser and the admin server is over secure HTTP.

This server can also be started manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/start_admin.

agentd.

This is the Partner Agent server that runs the ActiveAgent programs that perform the back-end ECXpert interactions. Partner Agent Server offers a decoupled architecture that separates the incoming communications-handling processing from the business logic processing. The agentd daemon executes the business logic. This architecture offers valuable security benefit,s such as the ability to partition the servers in a demilitarized (DMZ) firewall configuration.

This server can also be started manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/start_agentd.

ftpd.

This is the Partner Agent FTP server. It can be configured to accept either plain incoming FTP sessions or SSL-encrypted FTP sessions.

This server can also be started manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/start_ftpd.

httpd.

This is the Partner Agent HTTP server. It can be configured to accept either plain HTTP sessions or secure HTTP sessions.

This server can also be started manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/start_httpd.

Stopping Partner Agent Server

---

To shut down the Partner Agent Server:

1. Enter the ECXpert URL in your browser.




Enter the following URL in your browser:



http://<hostname>:<port>/



where <hostname> is the name of the host machine where ECXpert is installed, and <port> is the port number ECXpert is using.



The ECXpert home page is displayed, as shown in Figure 1-4.



2. Click the Admin link. The initial screen for the Server Administrative Interface is displayed. If the ECXpert Administrative Server is running, the Management tab appears as shown in Figure 1-5.



3. Toggle the PA Server switch to the Off position.



4. Click the Update Screen button after ten seconds has passed.




The screen is updated to reflect the change you just made.

When the Partner Agent Server is stopped, the following servers are shut down:

admin.

This is the Partner Agent administrative HTTPS server that provides a browser-based user interface to configure the Partner Agent Server installation.

This server can also be shut down manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/stop_admin.

agentd.

This is the Partner Agent server that runs the ActiveAgent programs that perform the back-end ECXpert interactions.

This server can also be shut down manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/stop_agentd.

ftpd.

This server can also be shut down manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/stop_ftpd.

This is the Partner Agent FTP server.

httpd.

This is the Partner Agent HTTP server.

This server can also be shut down manually from the command line by running the script $NSBASE/NS-apps/paserver/bin/stop_httpd.