# Chapter 5 – Technical Reference

#

## 5.1 – Installation Directories

This section identifies all standard files and directories of a normal IPS installation, as well as describes their contents and which platform they are designed for.

Path | Description | Platform
--- | --- | ---
    ips\
| This is the IPS root directory. It consists of IPS's subdirectories and a couple of IPS's core files. | (directory)
    ips\file_id.diz
| Standard archive description file. | -
    ips\ips2.exe
    ips\ips2.ico
| Main IPS executable with corresponding icon file. | OS/2
    ips\ips32.exe
| Main IPS executable. | Win32
    ips\readme.txt
| Small text file that redirects the reader to read the documentation\readme.txt and documentation\index.html files. | -
    ips\binaries\
| This directory contains all executables needed to run IPS and use all of its features. You should never run any of these programs directly. | (directory)
    ips\binaries\ips2cgi.exe
    ips\binaries\ips2cgi.ico
| IPS executable used to run CGI sessions with a corresponding icon file. | OS/2
    ips\binaries\ips2old.exe
    ips\binaries\ips2old.ico
| IPS Server executable used before last update with a corresponding icon file.. This file is automatically created as a backup file by the upgrade process. | OS/2
    ips\binaries\ips2srv.exe
    ips\binaries\ips2srv.ico
| IPS Server executable currently in use with a corresponding icon file. | OS/2
    ips\binaries\ips2upd.exe
    ips\binaries\ips2upd.ico
| IPS Server executable to be installed on next restart with a corresponding icon file. | OS/2
    ips\binaries\ips32cgi.exe
| IPS executable used to run CGI sessions. | Win32
    ips\binaries\ips32old.exe
| IPS Server executable used before last update. This file is automatically created as a backup file by the upgrade process. | Win32
    ips\binaries\ips32srv.exe
| IPS Server executable currently in use. | Win32
    ips\binaries\ips32upd.exe
| IPS Server executable to be installed on next restart. | Win32
    ips\binaries\ico\
| This directory contains a few additional icon files used by the IPS installation. | (directory)
    ips\binaries\ico\ipsfldr1.ico
| Icon for IPS folders. | OS/2
    ips\binaries\ico\ipsfldr2.ico
| Icon for IPS folders. | OS/2
    ips\config\
| All IPS configuration files (CFs) are located in the directory tree beneath this directory. Each subdirectory will contain one site personality. | (directory)
    ips\config\ips.cfg
| The main IPS configuration file which store system wide configuration settings for IPS internals. | -
    ips\config\<site>\
| Any one of these subdirectories contains a site personality configuration. | (directory)
    ips\config\<site>\<site>.cfg
| A site personality configuration file. Each one of these files defines a site personality's security, VFS tree and the services that run as part of that personality. IPS ships with one default site personality called "main", which is stored in ips\config\main, and defined in that directory's main.cfg file. | -
    ips\documentation\
| IPS documentation and default configuration directories are stored in this directory. | (directory)
    ips\documentation\index.html
| Main documentation entry point. If opened in a web browser, a convenient web-based interface to view IPS documentation can be used. | -
    ips\documentation\*
| All other directory entires are either documentation files or sub-directories containing default configuration directories. | -
    ips\log\
| Default directory for all log files written by the IPS system. | (directory)
    ips\log\ips2.log
| Main log file for IPS, here you will find system wide log entries as well as important error messages. | OS/2
    ips\log\ips32.log
Win32
    ips\log\<site>-<service>.log
| Service log files for any of the active services defined in the site personality. | -
    ips\log\ips*.trc
| Trace log files written when debug tracing has been enabled. These files contains detailed information about the internals when running IPS. | -
    ips\log\<yyyymm>\
| When log files are archived, a directory is created for each months log files. | (directory)
    ips\log\<yyyymm>\<yyyymmdd-hhmmss>.zip
| The log file archives. All files in the parent directory are automatically archived into this zip file whenever IPS is started up or restarted. The date and time are combined in a string of numbers to make up the filename. This makes it easy to locate a log that ends at a given point in time. The logs are easier to read since they're more compact than a single, monolithic log file. | -
    ips\messages\ftp\
| Multiple response message files and on-line help files for the FTPd service are placed in this directory. | (directory)
    ips\messages\ftp\ftp.hlp
| This file is used when a SITE HELP command is issued by the client over the FTP connection. | -
    ips\messages\ftp\ftp.res
| Response messages file used by the FTPd service component. | -
    ips\messages\ftp\login.msg
| Contains the message sent to a connecting client immediately after they log in to the FTPd service component with a non anonymous account. The file that IPS looks for (ie: this one) is determined by the path and filename setting in the file messages\ftp\ftp.res. | -
    ips\messages\ftp\login-anon.msg
| Contains the message sent to a connection client immediately after logging in to the FTPd service component with a anonymous account. The file that IPS looks for (ie: this one) is determined by the path and filename setting in the file messages\ftp\ftp.res. | -
    ips\messages\ftp\retr0.msg
| Message displayed when a user has downloaded (RETRieved) a file from the FTPd service component. The file that IPS looks for (ie: this one) is determined by the path and filename setting in the file messages\ftp\ftp.res. | -
    ips\messages\ftp\sitestat.msg
| Contains the message sent to the connected client when a user executes the SITE STAT command. The file that IPS looks for (ie: this one) is determined by the path and filename setting in the file messages\ftp\ftp.res. | -
    ips\messages\ftp\stor0.msg
| Message displayed when a user has uploaded (STORed) a file. The file that IPS looks for (ie: this one) is determined by the path and filename setting in the file messages\ftp\ftp.res. | -
    ips\messages\http\
| Multiple response message files and on-line help files for the HTTPd service are placed in this directory. | (directory)
    ips\messages\http\http.res
| Response messages file used by the HTTPd service component. | -
    ips\messages\http\icons\
| Default icons used internally by the HTTPd service component. | (directory)
    ips\messages\http\icons\button90x30-ips-2.gif
| “Powered by IPS” web page button. | -
    ips\messages\http\icons\header400x40-ipsadm.gif
| IPS Management header image. | -
    ips\messages\http\icons\icon20-file.gif
| Icon used to identify files in HTTP based directory listings. | -
    ips\messages\http\icons\icon20-folder.gif
| Icon used to identify directories in HTTP based directory listings. | -
    ips\messages\http\icons\icon20-ips.gif
| Small IPS icon. | -
    ips\messages\http\icons\icon40-ips.gif
| Large IPS icon. | -
    ips\messages\imap4\
| Multiple response message files and on-line help files for the IMAP4d service are placed in this directory. | (directory)
    ips\messages\imap4\imap4.res
| Response messages file used by the IMAP4d service component. | -
    ips\messages\pop3\
| Multiple response message files and on-line help files for the POP3d service are placed in this directory. | (directory)
    ips\messages\pop3\pop3.res
| Response messages file used by the POP3d service component. | -
    ips\messages\smtp\
| Multiple response message files and on-line help files for the SMTPd service are placed in this directory. | (directory)
    ips\messages\smtp\smtp.res
| Response messages file used by the SMTPd service component. | -
    ips\queue\
| This directory contains various queues used by IPS. You should not modify files in this directory tree while IPS is running. | (directory)
    ips\queue\mail\*.inc
| Contains the header part of incoming mail messages. | -
    ips\queue\mail\*.hdr
| Contains the header part of queued mail messages. | -
    ips\queue\mail\*.msg
| Contain the message part of incoming/queued mail messages. | -
    ips\queue\mail\*.lck
| A message lock file. Exists when a delivery is in progress for a given message. | -
    ips\scripts\ftp\
| RexxHooks used by the FTPd service component are stored in this directory. | (directory)
    ips\scripts\ftp\OnConnect.rexx
| Example RexxHook script that's called whenever a connection is made to the FTPd service component. This script is configured in the site personality configuration file. | -
    ips\scripts\ftp\OnSite.rexx
| Example RexxHook script that's called whenever a SITE command is sent to the FTPd service component. This RexxHook script is executed before internal SITE commands are processed. | -
    ips\scripts\ftp\OnUser.rexx
| Example RexxHook script that's called whenever a user has sent his/her user name to the FTPd service component. | -
    ips\scripts\http\
| RexxHooks used by the HTTPd service component are stored in this directory. | (directory)
    ips\scripts\imap4\
| RexxHooks used by the IMAP4d service component are stored in this directory. | (directory)
    ips\scripts\pop3\
| RexxHooks used by the POP3d service component are stored in this directory. | (directory)
    ips\scripts\smtp\
| RexxHooks used by the SMTPd service component are stored in this directory. | (directory)
    ips\tmp\
| Directory used by IPS for temporary files. This directory is automatically created by IPS. | (directory)
    ips\utilities\
| This directory contains utilities part of the default IPS distribution. You may add your own IPS related utilities to this directory as well. | (directory)
    ips\utilities\ips2con.exe
    ips\utilities\ips2con.ico
| IPS Console executable with corresponding icon file. | OS/2
    ips\utilities\ips32con.exe
| IPS Console executable. | Win32

## 5.2 – Service Components

This section describes the specifications that IPS's service components have been based on, and to what degree these specifications are supported. Additional functionality going beyond those specifications are also described here.

### 5.2.1 - FTP Component

#### Specifications

RFC | STD | Category | Relationship | Document title
--- | --- | --- | --- | ---
959 | 9 |  | Obsoletes 765 | File Transfer Protocol (FTP)
1579 |  | Informational |  | Firewall-Friendly FTP
1635 |  | Informational |  | How to Use Anonymous FTP
1639 |  | Experimental | Obsoletes 1545 | FTP Operation Over Big Address Records (FOOBAR)
2228 |  | Standards Track | Updated 959 | FTP Security Extensions
2389 |  | Standards Track |  | Feature negotiation mechanism for the File Transfer Protocol
2428 |  | Standards Track |  | FTP Extensions for IPv6 and NATs
2577 |  | Informational |  | FTP Security Considerations

#### Additional Features for Normal User Sessions

The follow table list the additional SITE commands available to all users:

Command | Description
--- | ---
SITE HELP {[command]} | Access the on-line help file for help, this help documentation is defined in the help file in the ftp.hlp file.
SITE IDLE {[seconds]} | View/set current idle time-out for the current session.
SITE LANG [language] | Change current response language.
SITE LIST | List a directory using the control connection. This is the same as the normal FTP LIST command however no data connection is needed.
SITE MLSD | List a directory using the control connection. This is the same as the normal FTP MLSD command however no data connection is needed.
SITE NAME {[name]} | View/set full name. Anonymous users can only view.
SITE NLST | List a directory using the control connection. This is the same as the normal FTP NLST command however no data connection is needed.
SITE PASS [new-password] | Change password if possible.
SITE STAT | View user information and statistics.
SITE WHO | List active sessions for the current service. Administrative use of this command displays additional information.
SITE XIPS XCMD | Activate IPS specific extended command connection. After activation the current session is no longer rfc compliant.

##### SITE XIPS XCMD

After this SITE command is issued, IPS will send various bits of information over the control connection, even if they are not a response to a specific command. The current session in which this command is issued will no longer be RFC compliant.

The responses sent by the server to the client after this, are of the format:

    IPS <command>|<code>|<parameter>|

where:

- <command> is the FTP command this response shall be associated with.

- <code> is the sub-code.

- <parameter> is a response specific value.

There may be any number of parameters, and extra parameters can be added to responses without further notice. Each parameter is always terminated with a | (pipe) character.

Defined extended command responses are:

Command | Response | Description
--- | --- | ---
APPE | IPS APPE|0|<xfered>| | <xfered> is a decimal value indicating the number of bytes appended to files so far.
RETR | IPS RETR|0|<xfered>| | <xfered> is a decimal value indicating the number of bytes downloaded so far.
RETR | IPS RETR|1|<filesize>|<filedate>| | <filesize> is a decimal value indicating the size of the file. <filedate> is the date of the file in the same format as MDTM returns.
STOR | IPS STOR|0|<xfered>| | <xfered> is a decimal value indicating the number of bytes uploaded so far.

#### Additional Features for Administrative User Sessions

The follow table list the addition SITE commands available to administrative users:

Command | Description
--- | ---
SITE EXEC [command] {[arguments] ..} | Execute any normal OS command and view the result as a normal multiple response. This functionality is provided by the example OnSite RexxHook.
SITE RADM CGET [path] {[section] {[ident]}} | Retrieves a value from a specified configuration file.
SITE RADM CSET [path] [section] [ident] [value] | Assigns value [val] to parameter [id] in section [sect] of configuration file at path [path].
SITE RADM INSTANT | Instantly perform the previous SITE RADM RESTART or SITE RADM SHUTDOWN command.
SITE RADM KILL [socket] {[socket] ..} | Kills the listed socket(s).
SITE RADM LIST [object] | Lists the system object. Available objects are SOCKETS, SERVICES and USERS.
SITE RADM RESTART | Restart IPS when no more sessions are active.
SITE RADM SHUTDOWN | Shuts down IPS when no more sessions are active.
SITE RADM UDUP [user] [newuser] | Duplicates an existing user [user] to user account [newuser].
SITE RADM UGET [user] {[section] {[ident]}} | Displays a value for parameter [ident] for user [user] in section [section] of the user account file. If this command is called with only a usre name as input it will return the complete user account file.
SITE RADM USET [user] [section] [ident] [value] | Sets a the value [value] for parameter [ident], for user name [user], in section [section] of the user account file.

### 5.2.2 – HTTP Component

#### Specifications

RFC | STD | Category | Relationship | Document title
--- | --- | --- | --- | ---
959 |  | Informational |  | Hypertext Transfer Protocol -- HTTP/1.0
1579 |  | Standards Track |  | Hypertext Transfer Protocol -- HTTP/1.1
1635 |  | Standards Track |  | An Extension to HTTP : Digest Access Authentication
1639 |  | Standards Track |  | HTTP State Management Mechanism
2228 |  | Informational |  | Use and Interpretation of HTTP Version Numbers
2389 |  | Experimental |  | A Trivial Convention for using HTTP in URN Resolution
2428 |  | Standards Track |  | Simple Hit-Metering and Usage-Limiting for HTTP
2577 |  | Experimental |  | Transparent Content Negotiation in HTTP
2296 |  | Experimental |  | HTTP Remote Variant Selection Algorithm -- RVSA/1.0
2518 |  | Standards Track |  | HTTP Extensions for Distributed Authoring -- WEBDAV

#### Fill-in-Blanks (FiBs)

IPS includes support for direct usage for FiBs expressions within files served by the HTTP service. FiBs parsing is only performed on file types and in directories configured in the service setup. You may also use the more standardized SSI support and it's #echo method to provide FiBs support for HTTP documents.

#### Server Side Includes (SSI)

IPS includes limited support for Server Side Includes (SSI). The following table list the syntax of the supported SSI methods. SSI parsing is only performed on file types and in directories configured in the service setup.

#echo
Usage: | <!--#echo fib=”<fib-expression>” -->
Description: | Echo the result of any given FiBs expression.
Parameter | Description | Default | Type
--- | --- | --- | ---
fib-expression | Any FiBs expression. | - | Required

#include
Usage: | <!--#include file=”<relativepath>” --> <!--#include virtual=”<filepath>” -->
Description: | Insert the contents of the given file.
Parameter | Description | Default | Type
--- | --- | --- | ---
relativepath filepath | The path of the file to include. | - | Required

### 5.2.3 – IMAP4 Component

#### Specifications

RFC | STD | Category | Relationship | Document title
--- | --- | --- | --- | ---

### 5.2.4 – POP3 Component

#### Specifications

RFC | STD | Category | Relationship | Document title
--- | --- | --- | --- | ---
1734 |  | Standards Track |  | POP3 AUTHentication command
1939 | 53 | Standards Track | Obsoletes 1725 | Post Office Protocol - Version 3
1957 |  | Informational | Updates 1939 | Some Observations on Implementations of the Post Office Protocol (POP3)
2195 |  | Standards Track | Obsoletes 2095 | IMAP/POP AUTHorize Extension for Simple Challenge/Response
2384 |  | Standards Track |  | POP URL Scheme
2449 |  | Standards Track | Updates 1939 | POP3 Extension Mechanism

### 5.2.5 – SMTP Component

#### Specifications

RFC | STD | Category | Relationship | Document title
--- | --- | --- | --- | ---
821 | 10 |  |  | Simple Mail Transfer Protocol
876 |  |  |  | Survey of SMTP Implementations
1047 |  |  |  | Duplicate Messages and SMTP
1428 |  |  |  | Transition of Internet Mail from Just-Send-8 to 8bit-SMTP/MIME
1652 |  | Standards Track | Obsoletes 1426 | SMTP Service Extension for 8bit-MIME transport
1830 |  | Experimental |  | SMTP Service Extensions for Transmission of Large and Binary MIME Messages
1845 |  | Experimental |  | SMTP Service Extension for Checkpoint/Restart
1846 |  | Experimental |  | SMTP 521 Reply Code
1869 |  | Standards Track | Obsoletes 1651 | SMTP Service Extensions
1870 | 10 | Standards Track | Obsoletes 1653 | SMTP Service Extension for Message Size Declaration
1891 |  | Standards Track |  | SMTP Service Extension for Delivery Status Notifications
1985 |  | Standards Track |  | SMTP Service Extension for Remote Message Queue Starting
2034 |  | Standards Track |  | SMTP Service Extension for Returning Enhanced Error Codes
2197 |  | Standards Track | Obsoletes 1854 | SMTP Service Extension for Command Pipelining

## 5.3 – System Variables

The following is an alphabetized list of all variables in IPS that can be used in FiBs expressions or from various hooks. These are system-wide variables that are valid for all service types. Following this, there is a section for each service component, that lists additional variables that are available only for the particular service.

Variable | Description | Availability
--- | --- | ---
session.<identifier> | User defined session variables (Only available within current session). |
service.<identifier> | User defined service variables (Available from any session of that service). |
configfile | Path of service configuration file. |
configsection | Section in service configuration file. |
connectduration | Duration of current session (seconds). |
connecttime | Start time of session (seconds since 1980). |
connections | Number of currently active connections with the current service. |
clientaddress | Client addresses that this service allows connection with. |
ctid | Client TID. |
date | Current date. (yyyy/mm/dd) |
debugflag | State of the DebugFlag as set for the current service in the site personality configuration file. |
idle | Current time idle. |
localhost | Local host name. |
logfile | LogFile from the site personality configuraton file. |
logflag | State of the LogFlag, as set for the current service in the site personality configuration file. |
platform | Returns the current OS platform IPS is running under. Values are "os2" or "w32". |
recv | Files received from user during this client connection. |
recvkb | kBytes received from user during this client connection. |
remotehost | Client host name. |
remoteip | Client IP address. |
sent | Files sent to user during this client connection. |
sentkb | kBytes sent to user during this client connection. |
sessions | Number of sessions currently active. |
sessions.anonymous | Number of sessions logged in as anonymous, including this session if logged in. |
sessions.ip | Number of sessions from the same IP address as the session. |
sock | Main socket of current client connection. |
time | The current time. (hh:mm:ss) |
timeout | Idle time-out value of current client connection. |
uptime | Server uptime. |
usr.admin | Administrative user flag. (0/1) |
usr.aliases | User aliases. |
usr.anon | Anonymous user flag. (0/1) |
usr.changepassword | User allowed to change password? (0/1) |
usr.clientaddress | User allowed client addresses. |
usr.ftp.recv | Files received from user by FTP. |
usr.ftp.recvkb | kBytes received from user by FTP. |
usr.ftp.recvkbs | Maximum received speed by FTP (kBytes/s). |
usr.ftp.sent | Files sent to user by FTP. |
usr.ftp.sentkb | kBytes sent to user by FTP. |
usr.ftp.sentkbs | Maximum send speed by FTP (kBytes/s). |
usr.fullname | Full (Real) name of user. |
usr.logindir | User initial login directory. |
usr.maxbandwidth | Maximum bandwidth used for each FTP transfer. |
usr.smtp.recv | Messages received for user. |
usr.smtp.recvkb | kBytes of message data received for user. |
usr.username | Name of user connected. |
vers | IPS version number. |
version | IPS version string. |
vers.compile | IPS compilation date and time. |

### 5.3.1 – FTP Component Variables

Variable | Description | Availability
--- | --- | ---
curdir ftp.directory | Current directory of the current client connection. The value is returned in VFS format relative to the current active root directory. (Non ftp.* version of this variable to be obsoleted soon) |
curdisk ftp.directory.os | Current directory of the current client connection. The value is returned as a fully resolved OS path so it can be used directly without having to deal with the internals of the IPS VFS system. (Non ftp.* version of this variable to be obsoleted soon) |
curpath ftp.lastaccess.os | The path of the last file or directory (whatever type last accessed) by the current session returned in a fully resolved OS path. (Non ftp.* version of this variable to be obsoleted soon) |
curroot ftp.rootdirectory | Defined root directory of the current session relative to the VFS configured default root directory. This value is returned in VFS format. (Non ftp.* version of this variable to be obsoleted soon) |
password ftp.anonymouspassword | String entered as a password for an anonymous user session. (Non ftp.* version of this variable to be obsoleted soon) |
status ftp.status | Current status of the current client session. (Non ftp.* version of this variable to be obsoleted soon) Possible values include: 0: Not logged, 1: Awaiting password, 10: Idle, 11: Retrieving a file; 12: Storing a file; 13: Listing a directory; 14: Executing a SITE command. |
timeoutmax ftp.timeoutmax | Value of TimeoutMax, as specified in the configuration file for the current service. (Non ftp.* version of this variable to be obsoleted soon) |
type ftp.type | Current transfer mode setting of this client session. The returned value are either “Text/AscII” or “Binary/Image” as defined in the FTP response file. (Non ftp.* version of this variable to be obsoleted soon) |

### 5.3.2 – HTTP Component Variables

Variable | Description | Availability
--- | --- | ---
http.!<headerfield> | All received Header fields from the web browser can be accessed through this variable. <headerfield> must always be written in upper case only. |
http.directory | Current directory being listed (Only available if request is for a directory). |
http.iconlink.large | HTML code displaying a normal IPS icon with a link to the IPS site. |
http.iconlink.small | HTML code displaying a small IPS icon with a link to the IPS site. |
http.itemaddress | Service list. |
http.itemconnected | Session list. |
http.itemdate | Date of file being listed (Only available if request is for a directory). |
http.itemhostaddress | Session list. |
http.itemhostname | Session list. |
http.itemicon | Type icon of file being listed (Only available if request is for a directory). |
http.itemidle | Session list. |
http.itemname | Name of file being listed (Only available if request is for a directory). |
http.itemobject | Session list. |
http.itempoolsize | Service list. |
http.itemport | Service list. |
http.itemprotocol | Service list. |
http.itemservice | Service list. |
http.itemsession | Session list. |
http.itemsessions | Service list. |
http.itemsize | Size of file being listed (Only available if request is for a directory). |
http.itemstatus | Session list. |
http.itemstatus | Service list. |
http.itemtid | Service list. |
http.itemtime | Time of file being listed (Only available if request is for a directory). |
http.itemusername | Session list. |
http.querystring | CGI querystring. |
http.request | Complete request line as client sent it. |
http.request.method | Method part of request line. |
http.request.uri | URI |
http.request.version | Version part of request line. |
http.service | Session list. |
http.serviceaddress | Session list. |
http.serviceport | Session list. |
http.serviceprotocol | Session list. |
http.status | Status number. |
http.statusmessage | Status description (Only available if request is about to return an error). |
http.statustext | One line status message. |

### 5.3.3 – IMAP4 Component Variables

Variable | Description | Availability
--- | --- | ---
(none defined) |  |

### 5.3.4 – POP3 Component Variables

Variable | Description | Availability
--- | --- | ---
messages pop.messages.count | Number of messages in the mailbox currently locked for processing by this session. Any new messages received after the mailbox was locked is not part of the resulting number. (Non pop.* version of this variable to be obsoleted soon) |
messagessize pop.messages.size | Total size of messages in the mailbox currently locked for processing by this session. The value is returned as a number of Bytes and any new messages received after the mailbox was locked is not part of the resulting size. (Non pop.* version of this variable to be obsoleted soon) |
status pop.status | The current status of the client session. (Non pop.* version of this variable to be obsoleted soon) Possible values include: 0: In "Authorization 1" phase, 1: In "Authorization 2" phase, 2: Amidst a transaction, 3: Update |

### 5.3.5 – SMTP Component Variables

Variable | Description | Availability
--- | --- | ---
smtp.!<headerfield> | Message header fields can be accessed through this variable. <headerfield> must always be written in upper case. |
domain | The domain that IPS is attempting to deliver the current message to. |
ident | Ident attempting to deliver message to. |
localdomain | Local domain represented by this service. |
messagename | The name of the message file. |
messagepath | The local path of the message file. |
smtp.deliverystage | Current stage of message delivery. This is to be used by any OnDelivery hooks. Possible values include: 0: Initial delivery starting (The hook is only started once for each message with this stage) | hookOnDelivery
smtp.recipient | Current message recipient, this variable is only available when running hookOnRcpt. | hookOnRcpt
smtp.remotedomain | Remote domain/host identification as received by the HELO/EHLO command. | After client sent HELO/EHLO command.
smtp.reversepath | Reverse path received by a MAIL command. | After client sent MAIL command.

## 5.4 – RexxHooks

This sections covers the technical details about the RexxHook implementation within the system. For general information about RexxHooks and the configuration of which hooks to use, please see Chapter 4 as well as this section here.

All RexxHooks can query any system variable listed in section 5.3 and should return “0” to continue session processing unmodified. To modify execution most hooks should return a valid service response line with the possibility of returning a multiple-line response in a file as an option. This would mean that some knowledge about the RFC specifications for the service in question is required. It is also possible to peek in the service message files to get an idea about what other responses is allowed for the action in question.

### 5.4.1 – RexxHook Call Backs

When IPS calls a RexxHook it always passes a session identifier as the first parameter which can be used to make callbacks into IPS to interact with the data and/or functionality within IPS itself. A set of callback methods are provided for use by Rexx scripts running directly under IPS as RexxHooks. A description of these callback methods are listed in the following tables:

ipsCFG
Usage: | Value = ipsCFG(Session, ConfigFile, Section, Ident);
Description: | Read values from a IPS style configuration file. This makes it easy for a RexxHook to interact with existing configuration files or their own additional ones.
Parameter | Description | Default | Type
--- | --- | --- | ---
Session | Session ID received from IPS when the hook was called. | - | Required
ConfigFile | Path of configuration file to read. This should be specified as a normal OS path and not a VFS based one. | - | Required
Section | Section in configuration file specified without the brackets. | - | Required
Ident | Ident within section. | - | Required
Value | Value of the configuration parameter. | - | Result

ipsLOG
Usage: | ipsLOG(Session, Text);
Description: | Writes one line of text to the service log file.
Parameter | Description | Default | Type
--- | --- | --- | ---
Session | Session ID received from IPS when the hook was called. | - | Required
Text | Text to write to the service log file. | - | Required

ipsVAR
Usage: | Value = ipsVAR(Session, Text);
Description: | Resolve an IPS FiBs expression.
Parameter | Description | Default | Type
--- | --- | --- | ---
Session | Session ID received from IPS when the hook was called. | - | Required
Text | Text with FiBs expression for IPS to resolve. | - | Required
Value | Returned and resolved FiBs expression. | - | Result

ipsSAY
Usage: | ipsSAY(Session, Text);
Description: | Sends a text string using the current sessions main socket connection.
Parameter | Description | Default | Type
--- | --- | --- | ---
Session | Session ID received from IPS when the hook was called. | - | Required
Text | Text to send to the connected client over the main socket connection. | - | Required

## 5.5 – DllHooks

### 5.5.1 – Basic DllHook Support

In addition to the Rexx script based hooks, IPS supports faster and more streamlined hooks by the use of 3rd party .DLL files. Wherever a Rexx hook can be specified you could also specify a DllHook.

Example configuration lines
    hookOnConnect=myhook.dll mymethod
    hookOnCommand=myhook.rexx

Please see the files in the ipshooks directory for more information and example source code for creating IPS DllHooks using Pascal og C/C++.

### 5.5.2 – External Password Authentication

IPS can be configured to authentication the passwords for incoming connections from any external sources. This is implemented by developing a .dll with a special function exported which performs the password authentication.

The .dll must be named ipsauth.dll, and it must export the function ipsAuthenticate . In addition to this, the Password field in the user file must be set to <external>.

This function is called with two zero terminated string pointers using the default OS calling convention and should return a 32-bit integer value of 0 for successful validation or any other error value to deny password authentication.

### 5.5.3 – HTTP Plug-Ins

Please ask for information about this through the mailing list.

## 5.6 – Service Hooks

Different hooks are defined for each type of service and the following sub sections describes the available hooks and what they should return to modify the default IPS processing of the session.

### 5.6.1 – FTP Hooks

RexxHook | Trigger action | Description
--- | --- | ---
hookOnConnect | Connection | This hook is called whenever a new session is opened against the server, before a login attempt is made. Return a response string to deny session establishment.
hookOnCommand | Any command | This hook is called for every command received from the client, before any internal processing begins. The command can be modified by this hook and returned to the system.
hookOnPass | PASS command | This hook is called after receiving a password from an anonymous user login. To deny login, return a response string.
hookOnRetr | RETR command | This hook is called before a retrieve (send to client) command is started. Return a response string to deny action.
hookOnSite | SITE command | This hook is called before internal processing of SITE commands occurs. Return a response string to skip internal processing.
hookOnStor | STOR command | This hook is called before a store (receive from client) command is started. Return a response string to deny action.
hookOnUser | USER command | This hook is called when a user has identified him/herself and been found in the user database. Return a response string to deny login.

### 5.6.2 – HTTP Hooks

RexxHook | Trigger action | Description
--- | --- | ---
(none defined) |  |

### 5.6.3 – IMAP4 Hooks

RexxHook | Trigger action | Description
--- | --- | ---
(none defined) |  |

### 5.6.4 – POP3 Hooks

RexxHook | Trigger action | Description
--- | --- | ---
hookOnConnect | Connection | This hook is called whenever a new sessions is opened against the server before a login attempt is made. Return a response string to deny session.
hookOnCommand | Any command | This hook is called for every command received from the client before any internal processing begins. The command can be modified by this hook and returned to the system.
hookOnUser | USER and APOP commands | This hook is called when a user has identified themselves and have been found in the user database. Return a response string to deny login.

### 5.6.5 – SMTP Hooks

RexxHook | Trigger action | Description
--- | --- | ---
hookOnConnect | Connection | This hook is called whenever new sessions is opened with the server, just before a login attempt is made. Return a response string to deny establishment of a session.
hookOnCommand | Any command | This hook is called for every command received from the client before any internal processing begins. The command can be modified by this hook and returned to the system.
hookOnData | Incoming DATA command | This hook is called when a full message body has been received before the client is given an final result. The hook may reject the message by returning a response string.
hookOnDelivery | Local and/or remote delivery process. | This hook is called at various stages during the message delivery process. The current stage identification can be found by querying the smtp.deliverystage session variable. A return value for 0 (False) means that the stage may continue and a return value of 1 (True) means that the stage shall be aborted.
hookOnHelo | Incoming HELO/EHLO command | This hook is called whenever a message delivery session is initiated from a remote server. Hook should return 0 to accept the session or a valid response to reject the session.
hookOnMail | Incoming MAIL command | This hook is called when a new message “sender” is received for the current message transaction. Hook should return 0 to accept the transaction to continue or a valid response to reject the “sender”.
hookOnRcpt | Incoming RCPT command | This hook is called when a new message recipient is received from the remote server for the current message transaction. Hook should return 0 to accept the recipient or a valid response to reject the recipient.

This document is the exclusive property of Terje Flaarønning.