Chapter 8   (Optional) Using the Server ActiveAgents

This chapter describes ActiveAgents, Server side programs that are triggered by user activity on the Server, and how to set them up.

The following topics are discussed in this section:

• Introducing ActiveAgents



• Agent Access



• Agent Server Port



• ActiveAgents



• ActiveAgent Descriptions

Introducing ActiveAgents

---

ActiveAgents are triggered when certain events occur, for example when a user logs in or out, when a file transfer is initiated or completed, or as a file filters during transfer.

The following types of agent processes are supported.

• Login agents are run when a user logs into the Partner Agent Server.



• Logout agents are run when a user disconnects from the Partner Agent Server.



• Incoming agents are run when files are being uploaded to the Partner Agent Server.



• Outgoing agents are run when files are being downloaded from the Partner Agent Server.



• Cert agents are run during the SSL negotiation if certificate verification is enabled.



• Auth agents are run when the PASS command is received from a client.



• Config agents are run when the USER command is received from a client.



• FTP/HTTP commands are run when particular FTP or HTTP commands are received from a client.



• FTP commands are run when particular FTP commands are received from a client.

Several ActiveAgents that work specifically with ECXpert are automatically installed with the Partner Agent Server (see "ECXpert ActiveAgents").

ActiveAgent Server

ActiveAgents are started by the ActiveAgent Server (agentd daemon) that was installed during the Partner Agent Server installation. The agentd routes packets between Partner Agent Server file transfer processes and the ActiveAgents. You can run your agentd on a different Server machine from your Partner Agent Server, thereby creating a multi-tiered architecture where agent processes are run on the remote ActiveAgents Server. This architecture has many security benefits, as well as the scalability benefit of being able to create multi-tiered file processing applications.

---

Note

To run your agentd on different Server from your Partner Agent Server, you must install Partner Agent Server on both Servers, and you must configure both ActiveAgent systems identically. The ActiveAgent system relies on the following configuration files being identical on the Partner Agent ftpd and agentd Servers: $NSBASE/NS-apps/paserver/conf/agentd.conf $NSBASE/NS-apps/paserver/conf/agentd.host $NSBASE/NS-apps/paserver/conf/agentd.user $NSBASE/NS-apps/paserver/conf/agents.conf

---

Environment Variables

ActiveAgents can process parameters passed in as environment variables. Some types of incoming and outgoing agents act as filters on files and so must be able to either accept or generate file streams on the standard UNIX I/O streams (stdin and stdout). An ActiveAgent can be written in several languages such as C, C++ and PERL.

An ActiveAgent is passed any optional arguments that were specified at configuration time. The calling sequence for an ActiveAgent is:

agent [optional arguments]

The environment variables that are passed into ActiveAgents take the form:

DXAGENT_VARNAME=value environment variables

The environment variables that are passed into ActiveAgents are:

Environment Variable Name	Description
DXAGENT_TARGET	This variable is set to the filename matching a target wildcard in the agents.conf file for incoming or outgoing agents, or the user name for auth, config, login, and logout agents.
DXAGENT_TARGETDIR	This is the dirname portion of the fully qualified target path, relative to the root of the filesystem in effect for this user.
DXAGENT_TARGETPATH	This is the dirname portion of the fully qualified target path, relative to the real root of the filesystem. For real users, DXAGENT_TARGETDIR and DXAGENT_TARGETPATH are the same. For anonymous users, DXAGENT_TARGETPATH is the concatenation of the DXAGENT_ROOTDIR and DXAGENT_TARGETDIR variables. For virtual users, DXAGENT_TARGETPATH is the concatenation of the DXAGENT_HOMEDIR and DXAGENT_TARGETDIR variables.
DXAGENT_FULLTARGET	Complete absolute pathname of the target.
DXAGENT_CERTCOOKIE	The variable that is set by the cert agent. For more information on cookies, "Notes on Agent Supplied Cookies".
DXAGENT_AUTHCOOKIE	The variable that is set by the auth agent. For more information on cookies, "Notes on Agent Supplied Cookies".
DXAGENT_USERCOOKIE	The variable that is set by the user agent. For more information on cookies, "Notes on Agent Supplied Cookies".
DXAGENT_COOKIE	A persistent cookie that can be set by the cert, auth or login agents. The last cookie that is set by one of these three agents. If no cookie is supplied the value of this variable is null. For more information on cookies, "Notes on Agent Supplied Cookies".
DXAGENT_PWD	The current working directory in which the user is logged in.
DXAGENT_ROOTDIR	The filesystem root in effect for a user. For real and virtual users, this is always /. For anonymous users, this is the directory that anonymous logins get chrooted into.
DXAGENT_HOMEDIR	The users home directory. For real and virtual users, this is their home directory as obtained from their passwd file entry. In the case of virtual users, this is the directory we perform a virtual chroot into, and always appears as / to the virtual user. For anonymous user, this is always /.
DXAGENT_REMOTEHOST	The DNS name of the host the client is connecting to the Partner Agent Server from. Note: In a proxy environment, this can be the name of the proxy Server host.
DXAGENT_REMOTEADDR	The IP address of the host the client is connecting to the Partner Agent Server from. Note: In a proxy environment, this can be the address of the proxy Server host.
DXAGENT_LOGINNAME	Login name of the user.
DXAGENT_LOGINPASS	Password of the user (email address for anonymous users).
DXAGENT_USERTYPE	The user type (real, anonymous, guest or virtual).
DXAGENT_CLIENT	The client that connected to agentd to trigger this agent. Typically this is a Partner Agent Server ftpd or httpd.
DXAGENT_TRIGGER	The agent trigger type.
DXAGENT_TYPE	The agent type.

Notes on Agent Supplied Cookies

• If an auth agent is defined, the first line of output, up to a \n, is treated as a cookie.



• If the first line of output of a cert, auth or login agent consists solely of the \n character, it is considered to be a NULL cookie.



• If there is no cert, auth or login agent defined, or if the agent supplied cookies are NULL, there is no cookie, and the DXAGENT_COOKIE environment variable is not set.



• If a login agent is also defined, the first line of output, up to a \n, is treated as a cookie and overwrites the auth agent supplied cookie. If the first line of output consists solely of the \n character, it is considered a NULL cookie and the auth agent supplied cookie remains in force. When a login agent is not defined, the auth agent cookie is continued to be used for the rest of the session.



• The cert cookie sets the DXAGENT_CERTCOOKIE environment variable.



• The auth cookie sets the DXAGENT_AUTHCOOKIE environment variable.



• The login cookie sets the DXAGENT_USERCOOKIE environment variable.



• The DXAGENT_COOKIE environment is set to the last cookie supplied by an agent.

Bundled ActiveAgents

Partner Agent Server comes bundled with several ActiveAgents:

• A Login and a Logout agent that demonstrate how to use the DXAGENT_TARGET variable in login/logout agents.



• An Incoming End agent called notify that sends e-mail to the user ftp@localhost whenever a new file is uploaded into the /incoming/ directory.



• An Outgoing End agent called notify that sends e-mail to the user ftp@localhost whenever a file is downloaded from the /pub/ directory.



• A cert verify agent called verify that demonstrates how to preform custom client certificate verification. It works in conjunction with client certificates generated by gencerts.

Agent Access

---

The Agent Server Host Access page is where you set up the rules that determine which Partner Agent Servers are allowed to connect to the agentd ActiveAgents Server. The access rules allow and deny access from programs and network IP addresses. It is important to confine access to the agentd Server to trusted hosts and to trusted applications. The preferred applications are the Partner Agent Server ftpd and httpd processes.

ActiveAgent Server Host Access rules either allow or deny access to the agentd Server by host name or host IP address. When a process tries to connect to the agentd to run an ActiveAgent, the agentd Server applies its access rules to determine if the connecting process is allowed to run ActiveAgents. Because you could have some fairly powerful ActiveAgents defined, you should maximize the security of the ActiveAgent Server Access rules to prevent unauthorized programs from attempting to run ActiveAgents.

Figure 8-1    Agents pages, Agent Server Host Access screen

Reordering the Rules

The order that the access rules are applied is important, and can be configured. The default setting is that deny rules are applied first, followed by the allow rules. The most typical, and default, configuration is to deny access from all Servers (deny from *), and then to allow access only from localhost.

To change the order that the access rules are applied:

1. Select the rule order, (Allow then Deny or Deny then Allow), from the drop-down list in the Rule Order section.



2. Click Change Order.








---

Note	Do not set the order of the rules to be Allow then Deny and also have a rule that denies connections from *. If you do, no processes are allowed to connect to your ActiveAgent agentd Server.

---

Adding a New Agent Server Host Access Rule Entry

To add a new Agent Server Host Access rule:

1. Select if the rule is an allow or a deny rule from the Rule drop-down list.



2. Enter the IP address or host name of the Server that is to be allowed or denied, in the Address field. You may use UNIX-style wildcards such as *. For example, allowing connections from *.mydomain.com allows Partner Agent Servers from the mydomain.com network to connect to your ActiveAgent agentd Server.



3. Select the client process from the Server Client drop-down list.



4. Click Add Entry.




The rule is added to the list of Current Agent Server Host Access Entries, with a status of Disabled.

Enabling or Disabling an Agent Server Host Access Rule Entry

To enable or disable an agent Server host access rule, click Enable or Disable, next to the desired rule.

Editing an Agent Server Host Access Rule

To edit an agent Server host access rule from the list of Current Agent Server Host Access Entries:

1. In the Action column, next to the desired class definition, click Edit.



2. Make the desired changes in the fields and drop-down lists in the Edit Agent Server Host Access Entry section above the list of Current Agent Server Host Access Entries.



3. Click Apply.




Your changes are reflected in the list of Current Agent Server Host Access Entries.

Deleting an Agent Server Host Access Rule

To delete an agent Server host access rule, in the Action column, next to the desired rule, click Delete.

Agent Server Port

---

The Agent Server Port page is where you configure the network port your ActiveAgents agentd Server is listening on for Partner Agent Server connections.

Figure 8-2    Agents pages, Agent Server Port screen

The default port is 4455. To change the network port:

1. Enter the port in the Agent Server Port field.



2. Click Apply.




When you change the port, the agentd Server is re-initialized with this new port. All new Partner Agent Server sessions connect to the agentd on the new port.

ActiveAgents

---

There are a number of events that can trigger the ActiveAgent agentd Server to run an agent. You can define a different agent for each user type, and you can specify that filenames match your predefined target filename patterns before an agent is run. This gives you the utmost flexibility in defining active Server-based processing that is integrated with your file transfers.

The ActiveAgents page displays any ActiveAgents that have been configured. You can enable, disable, or remove any ActiveAgent in the list of Current ActiveAgents Entries. You can also add new ActiveAgent entries.

The ActiveAgent programs shown in Figure 8-3 are preconfigured and preinstalled for Partner Agent Server.

Figure 8-3    Agents pages, Active Agents screen

An ActiveAgent entry consists of the following items.

• Agent Type lists the type of the agent.



• User lists the user name, (or users via wildcards), which causes this agent to be executed (in conjunction with the target).



• Execution lists if the execution permissions of the agent are User/Group or for an FTP user.



• Exec As User lists which user ID the agent runs as.



• Exec As Group lists which group ID the agent runs as.



• Target lists the filenames that trigger the agent.



• Agent lists the ActiveAgent name.



• Server lists the IP address of the ActiveAgents agentd Server that Partner Agent Server connect to. Typically your agentd runs on the same machine as your Partner Agent Server ftpd.



• Port lists the port of the ActiveAgents agentd Server that Partner Agent Server connect to.



• Status displays whether the particular agent is enabled or disabled.

Chaining ActiveAgents

The same event and target can invoke more than one Agent. This is known as chaining agents. The Agents are invoked in the order they appear in the list of Current Active Agent Entries. To change the order of chained agents, use the arrows next to the left of the entries in the list of ActiveAgent Entries.

Adding a New ActiveAgent Entry

To add and configure a new ActiveAgent entry:

1. Select the agent type from the Agent Type drop-down list.



2. Select a user name that you want to trigger your agent, (in conjunction with the target), from the User drop-down list.



3. Select, from the Execution drop-down list, whether you want the ActiveAgent to run with specified User/Group permissions or with the permissions of the user who triggers the ActiveAgent.








---

Note	If the agent is to be run with the user group and ID of the user who is logged in to Partner Agent Server, then a "—" is displayed in the next two fields.

---



4. Select the User who's permissions you want to run the ActiveAgent with, from the Exec as User drop-down list.



5. Select the User Group who's permissions you want to run the ActiveAgent with, from the Exec as Group drop-down list.



6. Enter a Target filename pattern that triggers the agent in the Target field. The incoming or outgoing agent only runs if the filename that is being transferred matches the target of an Incoming or Outgoing agent (depending on whether the file is being uploaded or downloaded). UNIX-style wildcards are permitted. For example, a Target of *.exe matches all files with a suffix of .exe, while a Target of * matches all files.








---

Note

All target matching is done with an absolute path, so if you want to match a target in any directory, prepend the wildcard character * to the target. For example, to match the target README in any directory, use *README and not just README. In addition, all targets must be specified based on the file system root in use by the user. For anonymous FTP, this is the directory specified in the FTP user account. For example, if the FTP hierarchy is rooted in /home/ftp, and the target is /home/ftp/incoming/foo, you must only specify /incoming/foo as the target. Similarly, for virtual users, this is the virtual root directory specified in the virtual password file. For example, if the virtual root is /home/ftp/virtual/user1 and you want to specify a target of /home/ftp/virtual/user1/bar, you must only specify /bar as the target.

---



7. Enter the name or pathname of the executable agent program or script in the Agent field. If you do not specify an absolute pathname, agentd searches in $NSBASE/NS-apps/paserver/bin/agents/ for the agent executable.



8. Enter any command-line arguments that you want to pass to the agent in the Arguments field.



9. Enter the Host IP address of the ActiveAgent agentd Server in the Server Address field. This can be your loopback address (typically 127.0.0.1) if the agentd and the Partner Agent Server ftpd are running on the same machine.



10. Specify the port on which the agentd is listening for connections in the Server Port field.



11. Click Add Agent.




The new agent definition is added to the list of Current ActiveAgent Entries with a status of Disabled.

Enabling or Disabling an ActiveAgent entry

To enable or disable an ActiveAgent entry, click Enable or Disable, next to the desired entry.

Editing an ActiveAgent entry

To edit an ActiveAgent entry from the list of Current ActiveAgent Entries:

1. In the Action column, next to the desired class definition, click Edit.



2. Make the desired changes in the fields and drop-down lists in the Edit ActiveAgent Entry section above the list of Current ActiveAgent Entries.



3. Click Apply.




Your changes are reflected in the list of Current ActiveAgent Entries.

Deleting an ActiveAgent entry

To delete an ActiveAgent entry, in the Action column next to the desired entry, click Delete.

ActiveAgent Descriptions

---

The following ActiveAgents are bundled with Partner Agent Server.

Certificate Agent (cert)

The cert agent is invoked during the SSL negotiation if certificate verification is enabled. The cert agent receives the client certificate in PEM-encoded format via standard input, and is delimited by:

-----BEGIN CERTIFICATE-----
<base-64 certificate data>
-----END CERTIFICATE-----

This certificate may be decoded and then validated via any mechanism desired. The agent is required to output multiple lines of information. Each line is terminated with the newline character. The lines have the following significance:

Line 1	specifies the certificate cookie which is used to identify the session. This cookie is passed to other agents to allow state maintenance across agents.
Line 2	specifies the local user name that Partner Agent Server uses to set up the permissions of this user.
Line 3	... n are sent back to the client as a Server side message. The client displays this information in the interactive FTP session, or in its logs.

The agent also returns an exit code which determines how the results are interpreted:

Exit code 0	This user is authenticated, require password authentication with user returned.
Exit code 1	This user is authenticated, do not require a password.
Any other exit code	This user is not authenticated, terminate the SSL negotiation and disconnect session.

User Configuration Agent (config)

The config agent is called immediately after receiving the USER command from a client. The config agent can provide per user information to the Partner Agent Server such as a password file entry, upload restrictions and access control.

In the following example, a password entry for the user demo is provided so that an etc/passwd entry on the system running Partner Agent Server is not needed. In addition, the user is tagged as virtual, effectively chrooting to the virtual user's home directory, without requiring an anonymous login. The config agent output is:

[passwd]
virtual demo: <password>:4000:4000:Agent Demo:/tmp/demo:/bin/csh

The following example demonstrates how you can provide access control on a per user basis. The default rule order for Partner Agent Server is defined as deny then allow in paserver.host. This can be changed to allow then deny.

The rule, shown below, only allows the user demo access to Partner Agent Server via localhost.

[access]
allow demo localhost
deny demo *

Password Authentication Agent (auth)

The auth agent is called immediately after receiving the PASS command from a client. The first line of output, up to a \n is treated as an auth cookie by the Partner Agent Server. Remaining lines are sent transparently to the user as an authentication phase message. The agent is required to output multiple lines of information. Each line is terminated with the newline character. The lines have the following significance:

Line 1	specifies the authentication cookie which can be used to identify this session. This cookie is passed to other agents to allow state maintenance across agents.
Line 2	... n are sent back to the client as a Server side message. The client displays this information in the interactive FTP session, or in its logs.

Any non-zero exit status is treated as an authentication failure by Partner Agent Server.

---

Note	An auth agent is never invoked for anonymous logins.

---

There are two filedrive.conf directives: auth_magic and auth_order. The default filedrive.conf contains the following two lines:

auth-magic @
auth-order agent passwd

If auth-magic is defined, its value is used to check against the <password> field. If it matches, only the auth agent is called. If the value does not match, only standard password based authentication is used.

If auth-magic is not defined, the auth-order is checked. If the auth-order directive is passwd agent, standard password based authentication is used. If it fails, the auth agent is called as a second chance.

If the auth-order directive is agent passwd, the auth agent is called. If it fails, standard password based authentication is used as a second chance.

A non-existent auth agent is considered an authentication failure. For example, if auth-order is agent passwd, and there is no agent, the first round of authentication fails and standard password based authentication is attempted for the second round.

If auth-order is not defined, only standard password based authentication is done.

Login and Logout Agents

Login Agent

The login agent exit status is ignored and no longer has any effect on the login process. It is called in the first stages of the login after all authentication has been completed.

The first line of output, up to a \n is treated as a login cookie by the Partner Agent Server. All remaining lines are sent transparently to the user as a login message.

Logout Agent

The logout agent is called when the user session is terminated. Any output is sent transparently to the user as a logout message.

Incoming and Outgoing Agents

Incoming and outgoing agents are used for some of the following reasons when you are uploading and downloading files from a Server for data transmission:

• To push data back and forth.



• To allow permissions to be granted to connect to a Server.



• To deny permissions to connect to a Server.



• To notify the system administrator or other designated users when files have been uploaded to or downloaded from the Server.

Incoming Agents

Incoming agents occur whenever you perform an upload to the Server.

Incoming Start Agent

This agent is called at the beginning of an upload. Permissions can be given or denied for users to connect to the Server through the Incoming Start Agent.

Incoming End Agent

This agent is called at the end of an upload session. It primarily alerts someone that files have been uploaded to the Server.

Incoming Error Agent

This agent is called when an unexpected interruption occurs during a file upload to the Server. The most common reason for this type of error is usually due to a network problem.

Incoming Abort Agent

This agent is called when you want to perform an intentional interruption of a file transmission. This can be done through [Control-C], break, or some other kill method.

Outgoing Agents

Outgoing agents occur whenever you perform a download from the Server.

Outgoing Start Agent

This agent is called at the beginning of a download. Permissions can be given or denied for users to connect to the serve through the Outgoing Start Agent.

Outgoing End Agent

This agent is called at the end of a download session. It primarily alerts someone that files have been downloaded from the Server.

Outgoing Error Agent

This agent is called when an unexpected interruption occurs during a file download from the Server. The most common reason for this type of error is usually due to a network problem.

Outgoing Abort Agent

This agent is called when you want to perform an intentional interruption of a file transmission. This can be done through [Control-C], break, or some other kill method.

FTP and HTTP Command Agents

If a command agent is defined for a particular command, Partner Agent Server does not perform any action for the command, except to invoke the agent and send a response based on the agent's exit status.

Every command that involves filesystem access has an associated agent. A non-zero exit status is treated as a command failure.

File Download	This agent generates data that is sent to the client.
File Upload	This agent handles any incoming data from the client.
Directory List	The LIST agent generates ls -al style listings.
Transfer Restart	The REST agent is used when restarting a previously upload or download transfer.
Modification Time	The MDTM agent displays the last modification time of a remote file.
File Size	The SIZE agent reports the size of the specified file. Only the first line of output up to a \n is sent to the client as the size. All other output is discarded.
MD5 Checksum	The RTCK agent is used to compute the digest of a file.
FTP Command Agent - CWD	The CWD agent is used to change the current working directory.
FTP Command Agent - DELE	The DELE agent is used to delete a file. It is subject to the Partner Agent Server delete restrictions.
FTP Command Agent - MKD	The MKD agent is used to make a new directory. It is subject to the Partner Agent Server mkdir restrictions.
FTP Command Agent - NLST	The NLST agent generates ls -1 style listings. This is required for clients issuing the mget and mdelete commands.
FTP Command Agent - PWD	The PWD agent reports the current working directory. Only the first line of output up to a \n is sent to the client as the pwd. All other output is discarded.
FTP Command Agent - RMD	The RMD agent is used to remove a directory. It is subject to the Partner Agent Server rmdir restrictions.
FTP Command Agent - RNFR	The RNFR agent is used to examine the existence of the destination filename right after a rename command is issued.
FTP Command Agent - RNTO	The RNTO agent is used to rename a file to a new name.
FTP Command Agent - SITE	The SITE agent is used to send custom SITE commands to the FTP server.
FTP Command Agent - CHMOD	The CHMOD agent changes the modes and permissions of a file in place of the system chmod.
FTP Command Agent - MIRR	The MIRR agent gets a list of mirror locations for mirroring data in the form of a URL, including the pathname in the URL, hostname, and port of each mirror Server.