Chapter 5 - Technical reference

5.1 - Installation directories

In this section we will identify all standard directories of a normal IPS installation as well as describe their contents.

5.1.1 - Directory "ips\"

This is the IPS root directory, it contains all other IPS sub-directories as well as a few files.

Filename

Description

file_id.diz

Standard archive description file.

readme.txt

Small text file that directs the reader to the documentation\readme.txt file instead.

setupos2.cmd

Rexx script for setup under OS/2 Warp.

setupw32.bat

Batch file for setup under Windows NT/2000.

startips.cmd

Rexx script for startup under OS/2 Warp.

startips.bat

Batch file for startup under Windows NT/2000.

5.1.2 - Directory "ips\binaries\"

This directory contains all executables needed to run IPS and use all of its features. You should probably include this directory in your PATH and LIBPATH environment settings.

Filename

Description

history.bat

Batch file written by IPS to archive old log files. (Windows NT/2000 version).

history.cmd

Batch file written by IPS to archive old log files. (OS/2 Warp version).

ips2.exe

Main IPS executable currently in use (OS/2 Warp version).

ips2cgi.exe

IPS executable used to run CGI sessions. (OS/2 Warp version).

ips2con.exe

IPS console executable. (OS/2 Warp version).

ips2old.exe

Main IPS executable used before last update (OS/2 Warp version).

ips2upd.exe

Main IPS executable to be installed on next restart (OS/2 Warp version).

ips32.exe

Main IPS executable currently in use (Windows NT/2000 version).

ips32cgi.exe

IPS executable used to run CGI sessions. (Windows NT/2000 version).

ips32con.exe

IPS console executable. (Windows NT/2000 version).

ips32old.exe

Main IPS executable used before last update (Windows NT/2000 version).

ips32upd.exe

Main IPS executable to be installed on next restart (Windows NT/2000 version).

startos2.cmd

Rexx script for running IPS under OS/2 Warp. This script runs IPS in a loop to automatically restart IPS in the case of a software failure. You should never call this file from the directory it is in. Instead, call the same file from it's parent directory.

startw32.bat

Batch file for running IPS under Windows NT/2000. This script runs IPS in a loop to automatically restart IPS in the case of a software failure. You should never call this file from the directory it is in. Instead, call the same file from it's parent directory.

5.1.3 - Directory "ips\binaries\ico\"

Filename

Description

ips2.ico

Icon for IPS executables. (OS/2 Warp version).

ips32.ico

Icon for IPS executables. (Windows NT/2000 version).

ipsfldr1.ico

Icon for IPS folders. (OS/2 Warp version).

ipsfldr2.ico

Icon for IPS folders. (OS/2 Warp version).

5.1.4 - Directory "ips\config\"

All IPS configuration files (CFs) are located in the directory tree beneath this directory. Each subdirectory will contain one site personality.

Filename

Description

ips.cfg

Main IPS configuration file. This file is actually not very interesting as IPS implements multiple site personalities and therefore the site configuration file(s) are the interesting one. IPS ships with one default site personality called "main".

5.1.5 - Directory "ips\config\[site_personality]\"

Filename

Description

[site_personality].cfg

A site personality configuration file (CF). Each one of these files defines a personality's security, VFS tree and the services that run as part of that personality.

5.1.6 - Directory "ips\documentation\"

IPS documentation as well as the default configuration directories are stored in this directory.

Filename

Description

index.html

Main documentation entry point. Open this file in your web browser to view the IPS documentation.

*

All other files are documentation files and sub-directories containing default configuration directories.

5.1.7 - Directory "ips\log\"

Filename

Description

ips.log

Main IPS log file. Important errors are logged here, so please keep an eye on this one.

*.log

Service log files, as defined in the site personality CFs.

5.1.8 - Directory "ips\log\history\"

Filename

Description

[datetime].zip

Archived log files. All files in the parent directory are automatically archived here on each IPS startup (or restart).

5.1.9 - Directory "ips\messages\ftp\"

Multiple response message files and online help files for the FTPd service are placed in this directory.

Filename

Description

ftp.hlp

Help file for SITE HELP command of FTPd service component. The file name is defined in the site personality configuration file.

ftp.res

Response messages file used by the FTPd service component.

login.msg

Message displayed when a user logs in to the FTPd service component. The file name is defined in messages\ftp\ftp.res.

login-anon.msg

Message displayed when a guest logs in to the FTPd service component. The file name is defined in messages\ftp\ftp.res.

retr0.msg

Message displayed when a user has downloaded (RETRieved) a file from the FTPd service component. The file name is defined in messages\ftp\ftp.res.

sitestat.msg

Message displayed when a user executes the SITE STAT command to the FTPd service component. The file name is defined in messages\ftp\ftp.res.

stor0.msg

Message displayed when a user has uploaded (STORed) stored a file to the FTPd service component. The file name is defined in messages\ftp\ftp.res.

5.1.10 - Directory "ips\messages\http\"

Multiple response message files and online help files for the HTTPd service are placed in this directory.

Filename

Description

http\http.res

Response messages file used by the HTTPd service component.

5.1.11 - Directory "ips\messages\pop3\"

Multiple response message files and online help files for the POP3d service are placed in this directory.

Filename

Description

pop3\pop3.res

Response messages file used by the POP3d service component.

5.1.12 - Directory "ips\messages\smtp\"

Multiple response message files and online help files for the SMTPd service are placed in this directory.

Filename

Description

smtp\smtp.res

Response messages file used by the SMTPd service component.

5.1.13 - Directory "ips\queue\"

This directory contains various queues used by IPS. You should not modify files in this directory while IPS is running.

Filename

Description

mail\*

Queued mail messages.

5.1.14 - Directory "ips\scripts\ftp"

RexxHooks used by the FTPd service component is stored in this directory.

Filename

Description

rxOnConnect.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 CF.

rxOnPass.rexx

Example RexxHook script that's called whenever a guest users has sent a password to the FTPd service component. This script is configured in the site personality CF.

rxOnSite.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. This script is configured in the site personality CF.

rxOnUser.rexx

Example RexxHook script that's called whenever a user has sent his/her username to the FTPd service component. This script is configured in the site personality CF.

5.1.15 - Directory "ips\scripts\http"

RexxHooks used by the HTTPd service component is stored in this directory.

Filename

Description

*.rexx

RexxHooks used be the HTTPd service component.

5.1.16 - Directory "ips\scripts\pop3"

RexxHooks used by the POP3d service component is stored in this directory.

Filename

Description

*.rexx

RexxHooks used by the POP3d service component.

5.1.17 - Directory "ips\scripts\smtp"

RexxHooks used by the SMTPd service component is stored in this directory.

Filename

Description

*.rexx

RexxHooks used by the SMTPd service component.

5.1.18 - Directory "ips\utilities"

This directory contains the files IPS uses for file-level access control, as well as informational utilities used by IPS for startup and runtime. You should probably include this directory in your PATH and LIBPATH environment settings.

Filename

Description

chgrp.exe

UNIX-like utility to control group access (EA based access in OS/2 Warp only).

chmod.exe

UNIX-like utility to control user access (EA based access in OS/2 Warp only).

chown.exe

UNIX-like utility to control owner access (EA based access in OS/2 Warp only).

ipsmon.exe

Prototype connection monitor for Windows NT/2000 (Not supported).

ipsrexx.dll

Rexx DLL for IPS password checking, OS/2 Warp version only. (Not supported).

isos2.exe

Utility that tells IPS if the operating environment is OS/2 Warp, or not.

ls.exe

UNIX-like utility to list directories with IPS access (EA based access in OS/2 Warp only).

5.2 - Services components

This section describes which specifications the various service components are based on and in what degree they support those specifications. Additional functionality going beyond the specifications are also described here.

5.2.1 - FTP component

Specifications

RFC

Category

Relationship

Document title

959


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]}

Display help about available SITE commands.

SITE IDLE {[seconds]}

View/set current idle time-out.

SITE LANG [language]

Change current response language.

SITE LIST

List a directory using the control connection.

SITE NAME {[name]}

View/set fullname. Anonymous users can only view.

SITE NLST

List a directory using the control connection.

SITE PASS [new-password]

Change password.

SITE STAT

View user information and statistics.

SITE WHO

List active sockets.

SITE XIPS XCMD

Activate IPS specific extended command connection. After activation the current session is no longer rfc compliant.

SITE HELP
SITE IDLE
SITE LANG
SITE LIST
SITE NAME
SITE NLST
SITE PASS
SITE STAT
SITE WHO
SITE XIPS XCMD

After issued this setting will make IPS send various information on the control connection even if they are not a response to a specific command. When this is activated, the session using this feature is no longer rfc compliant.

The responses sent after this is enables has the format:

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

<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]

Execute any normal OS command and view the result as a normal multiple response.

SITE RADM CGET [path] {[sect] {[id]}}

Gets any value from any configuration file.

SITE RADM CSET [path] [sect] [id] [val]

Assigns value [val] to parameter [id] in section [sect] of CF at path [path].

SITE RADM KILL [socket] {[socket] ..}

Kills the listed socket(s).

SITE RADM LIST [object]

Lists the system object.

SITE RADM MONITOR [seconds]

Starts a real-time site monitor, and keeps it running for a total of [seconds] seconds.

SITE RADM RESTART

Restart IPS when all sockets are closed or at once if done twice.

SITE RADM SHUTDOWN

Shuts down IPS when all sockets are closed, or immediately if issued twice.

SITE RADM UDUP [user] [newuser]

Duplicates an existing user [user] to user account [newuser].

SITE RADM UGET [usr] {[sect] {[id]}}

Displays a value for parameter [id] for user [usr] in section [sect] of the CF.

SITE RADM USET [usr] [sect] [id] [val]

Sets a value [val] for parameter [id], for username [usr], in section [sect] of the CF.

SITE EXEC
SITE RADM CGET

This collection of commands are used to remotely administer the IPS server. The format of the commands are:

SITE RADM CGET [cfg-file] {[section] [ident]}
SITE RADM CSET [cfg-file] [section] [ident] [new-value]
SITE RADM UDUPE [user] [newuser]
SITE RADM UGET [user] {[section] [ident]}
SITE RADM USET [user] [section] [ident] [new-value]

They will return the value or error messages as found in the [SITE] section of the ipsftp file. The UGET command can be given only a user name as the input and will the return a printout of the whole user file.



SITE RADM CSET
SITE RADM KILL
SITE RADM LIST
SITE RADM MONITOR
SITE RADM RESTART
SITE RADM SHUTDOWN
SITE RADM UDUP
SITE RADM UGET
SITE RADM USET

5.2.2 - HTTP component

Specifications

RFC

Category

Relationship

Document title

1945

Informational


Hypertext Transfer Protocol -- HTTP/1.0

2068

Standards Track


Hypertext Transfer Protocol -- HTTP/1.1

2069

Standards Track


An Extension to HTTP : Digest Access Authentication

2109

Standards Track


HTTP State Management Mechanism

2145

Informational


Use and Interpretation of HTTP Version Numbers

2169

Experimental


A Trivial Convention for using HTTP in URN Resolution

2227

Standards Track


Simple Hit-Metering and Usage-Limiting for HTTP

2295

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

5.2.3 - POP3 component

Specifications

RFC

Category

Relationship

Document title

1734

Standards Track


POP3 AUTHentication command

1939

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.4 - SMTP component

Specifications

RFC

Category

Relationship

Document title

821



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

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

Here we provide you with an alphabetical list of all variables which can be used in FIBs expressions. The table below lists the system wide variables valid for all service types, and below there is a section for each service component listing additional variables available only in that service.

Variable

Description

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.

debugflag

State of the Debugflag from the site personality CF.

idle

Current time idle.

localhost

Local hostname.

logfile

LogFile from the site personality CF.

logflag

State of the LogFlag, as set in the site personality CF.

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.

sock

Main socket of current client connection.

sock.first

Main socket of first client connection on this service.

sock.next

Main socket of next client connection on this service.

sock.prev

Main socket of previous client connection on this service.

time

Current time.

timeout

Idle time-out value of current client connection.

uptime

Server uptime string.

usr.admin

Administrative user.

usr.aliases

User aliases.

usr.anon

Anonymous user.

usr.changepassword

User allowed to change password?

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.

vers.compile

IPS version, compilation date/time.

5.3.1 - FTP component variables

Variable

Description

curdir

Current directory of the current client connection.

curdisk

Root and current directory of the current client connection in OS format.

curpath

Full path of current/last file/directory action.

curroot

Root directory of current session.

password

Password typed by Anonymous user.

status

Status of client connection.

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

TimeoutMax from the group configuration file.

type

Transfer type setting of client connection..

5.3.2 - HTTP component variables

Variable

Description

querystring


5.3.3 - POP3 component variables

Variable

Description

messages

Number of message in mailbox.

messagessize

Total size of messages in mailbox (Bytes).

status

Status of client connection.

Possible values include:
0: In authorization 1, 1: In authorization 2, 2: In transaction, 3: Update

5.3.4 - SMTP component variables

Variable

Description

messagefile

Path of message body file.