Chapter 4 – Advanced Configuration

4.1 – Platform Settings (config\ips.cfg)

Your IPS server application has a small number of settings valid for the application as a whole, these are called platform settings and do require a full IPS restart if changed. The settings are using to modify the way IPS start up and executes. You will find these settings in the config\ips.cfg configuration file.

4.1.1 – Platform Settings [GLOBAL] Section

The GLOBAL section is the first section in the default configuration file and this section includes the settings in the table below:

Parameter	Description	Default¹	Type
DisableConfigCheck²	Enabling this setting will skip the configuration consistency check done whenever IPS is started. This check can automatically find and is possible correct errors within your configuration.	"0" (False)	Optional
DisableObjectCreate²	Enabling this setting will skip the creation of WPS objects or Start Menu items for IPS.	"0" (False)	Optional
DisableConsoleStart²	Enabling this setting will skip the automatic start of a local IPS console process. The console can be started manually at a later time if needed.	"0" (False)	Optional
DisableLogArchiving²	IPS includes a feature which will automatically archive old log files when starting or restarting after a failure situation. If you don't want this archiving feature enable this setting.	"0" (False)	Optional
DisablePersonalities²	List of site personalities to disable. This setting is used if you have any subdirectories of config\ which should not be attempted started as a site personality.	None	Optional
EnableEMXCompatibility²	If you need to run EMX based applications (OS/2 only) from within IPS you will have to enable this setting as there are a few limitations in the EMX runtime which require IPS to reduce its scalability some.	"0" (False)	Optional

¹Default is the value assumed by IPS when the parameter is missing from the configuration file.
²Any modification to the value of this parameter requires a restart.

4.1.2 – Platform Settings [ADMIN] Section

The ADMIN section is used to configure the built in administrative service component. This component is among others used to server the IPS Console locally or remote. All keywords here have the same meaning as the identical ones in the normal service component sections.

Parameter	Description	Default¹	Type
Address²	IP address of the interface the administration service should bind its port to. Leave blank for it to bind to all available local addresses.	Blank (Any address)	Optional
Port²	Port on which the administration service listens for connections on.	"4321"	Optional
ClientAddress	Client IP address and/or host name mask list to allow/deny connections from.	"!*"	Optional
DebugFlag	A number representing a bitmap of debug groups to enable for writing to the log file.	"0"	Optional
Host	Hostname assumed for this service, it is best if this is a valid DNS hostname.	-	Required
LogFlag	A number representing a bitmap of log groups to skip when writing to the log file.	"0"	Optional
Timeout	Any number of second which a client session can be inactive before it disconnected from the service.	"180"	Optional
Password	Password used by the various administrative clients to access this service. The password are stored here in clear text but are never sent over the Internet when a connection is opened.	-	Required

¹Default is the value assumed by IPS when the parameter is missing from the configuration file.
²Any modification to the value of this parameter requires a restart.

4.1.3 – Platform Settings [DEBUG] Section

IPS includes a very powerful system to trace down system problems which will help the developer, it should only be used when instructed to by IPS support as it will activate extensive logging which may affect system performance.

Parameter	Description	Default¹	Type
Trace²	Enabling this setting will activate extensive debug trace logging.	"0" (False)	Optional

¹Default is the value assumed by IPS when the parameter is missing from the configuration file.
²Any modification to the value of this parameter requires a restart.

4.1.4 – Platform Settings [UPGRADE] Section

When new versions of IPS are installed this section provides the information needed by IPS to perform various automated tasks during the upgrade. Even the upgrade itself can be performed automatically from a upgrade server on the Internet.

Parameter	Description	Default¹	Type
CurrentVersion	Automatically update field containing currently used IPS version.	Current IPS version²	Read only
CurrentBuild	Automatically update field containing currently used IPS build.	Current IPS build²	Read only
Auto	Not used³	-	-
Frequency	Not used³	-	-
Server	Not used³	-	-

¹Default is the value assumed by IPS when the Parameter is missing from the configuration file.
²These values are automatically update by IPS itself and should not be changed manually.
³The automated upgrade service is not yet available.

4.2 – Site Personalities (config\<site>\<site>.cfg)

IPS operation is based around so called "site personalities" and comes pre-configured with one site personality named "main". A site personality consists of one security configuration (object access, user accounts and groups), one virtual file system configuration and one or more service components. You may have any number of site personalities configured.

The configuration of site personalities is actually quite easy as it is just a matter of configuring another directory with requested configuration just like the config\main\ directory shipped with IPS. The site personality configuration file should always be named according to the directory name.

Keep in mind that if your setup does not require a separate security configuration you can probably do your setup with only one site personality by pointing various services to different root directories in the VFS tree. This will keep the overall configuration simpler and then probably easier to maintain.

A good example for the use of multiple site personalities is when you are hosting services for different companies with their own set of users. If you configure one site personality for each company they can all have their completely separate security setup. Even different accounts with the same name for each company is okay.

4.2.1 – Site Personalities [GLOBAL] Section

Each site personality has a few global settings valid for the personality as a whole, these settings contains information about which services to start, the site administrator, location of some important directories as well as a list of defined user groups.

The parameters in the [GLOBAL] section is described in the table below:

Parameter	Description	Default	Type
ServiceSections	A list of service sections activated defined in this file. By removing section names from this list you effectively disables that service without having to remove its configuration from the file.	-	Required
SiteAdminMail	E-mail address for the main administrative user of the current site personality. This should be a valid address but does not need to be local to this server.	-	Required
SiteAdminUser	User ID for the main administrative user of the current site personality. Also known as root on UNIX systems.	-	Required
SiteDescription	Short informational text describing your site.	-	Required
HomeDirectory	Root directory for the users home directories. (VFS format)	-	Required
StatDirectory	Directory for the statistics files, relative to IPS-root or absolute. (OS format)	-	Required
UserDirectory	Directory for the user files, relative to IPS-root or absolute. (OS format)	-	Required
GroupsDefined	A list of defined user groups.	-	Required

4.3 – Security

Within a site personality all services share the same security setup. Security configuration is done by configuring a number of:

Accounts
Groups
Object access masks

Object access is based on physical path masks against the objects available in the servers file system(s). Each mask provides access for the mask owner (an account), mask group (one group) and any others.

4.3.1 – Accounts

An user account defines the named (users with accounts) and nameless people (anonymous users) who make up the community IPS is to serve. Each user has their own account, and the file representing their account is stored in the directory pointed to by the [GLOBAL].UserDirectory setting of the site personality configuration file. Each of these files contains properties, which are described in the table below.

[USER] Section

The following table describes the various parameters in the [USER] section of a user account file:

Parameter	Description	Default¹	Type
Username	This is the name of the user. The name specified here must match the file name of the user file; otherwise, the account will be disabled. User names are not case sensitive, but you may enter them names with mixed case for display purposes as desired.	-	Required
Fullname	The full name of the user.	-	Optional
Aliases	A list of Username aliases. These are just like having multiple usernames. This feature is often used to provide multiple e-mail idents for the same account.	-	Optional
MemberOfGroups	List of the groups this user is a member.	-	Optional
Password	Encrypted account password. When making a new user you can add a - in front of a non encrypted password and it will be encrypted on the first login. If set to the exact text "<external>", special external authentication is expected.	-	Optional
Secret	Encrypted account password. This password is automatically created from “Password” when a user log in.	(Automatically created)	Optional
ChangePassword	Set to "1" (True) if this account can change its password, otherwise set to "0" (False). Administrative accounts override this property and cannot change their password remotely.	"0" (False)	Optional
Anonymous	Set to "1" (True) if this is an anonymous user account, otherwise set to "0" (False).	"0" (False)	Optional
Administrator	Set to "1" (True) if this is an administrative user account, otherwise set to "0" (False).	"0" (False)	Optional
RootDirectory	If this user should have a different virtual root then set this. This will override the RootDirectory setting of the service. (This parameter will be moved to become service specific in a later version of IPS. The parameter only affects FTP service components)	(Service setting)	Optional
LoginDirectory	If you want to direct a user to a specified directory at login, please set this here. This directory is relative to the virtual root for the user. (This parameter will be moved to become service specific in a later version of IPS. The parameter only affects FTP service components)	(Root directory)	Optional
ClientAddress	User's IP address allow/deny filter. The user can be allowed/denied access based on this IP filter. The format of this parameter is just like the same parameter at service component level.	"*"	Optional
MaxBandwidth	Maximum retrieve bandwidth in kBytes/s for each normal user session. (0 = no limitation)	"0"	Optional

¹Default is the value assumed by IPS when the parameter is missing from the configuration file.

[ACCESS] Section

IPS offers the possibility to configure a special account specific [ACCESS] section which works together with the site personality [ACCESS] section. If there is an [ACCESS] section with access lines in the account file these access lines will be processed before the lines in the site personality configuration file.

Service Specific Sections

Each account file may also have account specific service parameters. These are configured within sections with the same name as the service sections in the site personality configuration. All such parameters are optional and some are only valid for specific service types (protocols).

Parameter	Description	Default¹	Type
DenyService	Deny account access to the current service.	"0" (False)	Any service
ForwardTo	List of local accounts or remote e-mail addresses to forward incoming mail received for this account to.	-	SMTP

¹Default is the value assumed by IPS when the parameter is missing from the configuration file.

4.3.2 – Groups

An account may be a member in a number of groups, these groups makes it easier to administer access as you can configure access on the group level. When an accounts is member of a group it will get the access defined for that group in addition to any access defined for the account itself and others.

4.3.3 – Object Access

Access to physical file system objects are defined through a series of access lines. These lines are processed one by one until a matching <path-mask> is found, the matching line is the used and no more lines are matched even if a line with a closer match is found below. The format of these lines are:

Access Line Format
<path-mask>;<owner>;<group>;<unix-access>;<restrictions>;

In the table below describes each field in the Access Line:

Section	Description
<path-mask>	A mask matching the physical file system structure you are defining access for. This should be fully qualified if you defined this path with a full qualified path in the VFS tree. Otherwise it should be a relative path matching the format used with defining the VFS mapping. Wild-chars “?” and “*” may be used at any position and a number of times in each mask.
<owner>	Owner (an account) of the objects matching this path-mask.
<group>	Group given access to by this access line.
<unix-access>	UNIX style standard access. This three digit number defines the basic access to the matching objects. The first digit defines the access provided to the owner, second digit defines group access and third digit defines other access. A table below list the various values available for each digit.
<restrictions>	This section defines restrictions to the access provided by the previous field. It is defined by a three digit number in the same matter as the previous field. A table below lists the various values available for each digit.

The following table lists the different digits used to build the <unix-access> field of an access line.

Standard Access	0 (---)	1 (--x)	2 (-w-)	3 (-wx)	4 (r--)	5 (r-x)	6 (rw-)	7 (rwx)
Read (r) Allow clients to read file information and data.	-	-	-	-	Allow	Allow	Allow	Allow
Write (w) Allow clients to write files information and data.	-	-	Allow	Allow	-	-	Allow	Allow
List/Execute (x) Allow clients to list directory contents and/or execute files (HTTP).	-	Allow	-	Allow	-	Allow	-	Allow

And, this table lists the different digits used to build the <restrictions> field of an access line.

Restrictions	0 (---)	1 (--d)	2 (-l-)	3 (-ld)	4 (e--)	5 (e-d)	6 (el-)	7 (eld)
Execute (e) Deny execute rights (HTTP).	-	-	-	-	Deny	Deny	Deny	Deny
List (l) Deny directory contents listing.	-	-	Deny	Deny	-	-	Deny	Deny
Delete (d) Deny delete access.	-	Deny	-	Deny	-	Deny	-	Deny

4.4 – Virtual File System

The VFS Tree (Virtual File System Tree) is a hierarchical file system structure, comprised of mappings of virtual names to actual locations on storage medium (local and elsewhere). The VFS Tree is not a directory structure that is to contain files. The VFS Tree is a virtual mapping of existing directories, unifying them to the extent that the administrator nor user need not be concerned about drive letters or mount points.

A few things about VFS trees:

The VFS Tree is defined beneath the [VFS] section heading in the site personality configuration file.

The VFS Tree must have a root, and this root must be mapped to a physical location on a storage medium (physical as opposed to virtual, meaning that the root must be mapped to an existing directory on a hard disk somewhere).
The VFS Tree is valid throughout all areas of the site personality.

There is no limit on the complexity of the VFS setup and you can have any number of VFS mappings in the format giving by the table below.

Format of the lines in the [VFS] section
[VFS] <virtual directory>=<physical directory>

In the following table there is an example of a simple VFS tree configuration.

Configuration	Description
[VFS]	Section heading which is required for IPS to find the VFS data within the configuration file.
/=c:\myvfsroot	Required root mapping, the directory "c:\myvfsroot" need to exists on your hard drive and all services within this site personality will see this as the default root directory unless overridden by a service or user specific RootDirectory entry which may point to any location in the VFS tree.
/d-drive=d:\	This map the virtual directory "d-drive" to the root of the physical partition named "d:". The directory "c:\myvfsroot\d-drive" must be created to act as a mount point, however when any service requests the directory "/d-drive" they will be directed to "d:\".
/d-drive/log=c:\ips\log	Here the virtual directory "/d-drive/log" will map to the physical directory "c:\ips\log". Again, you need to make sure there are a physical directory named "d:\log" which will serve as a mount point.

4.5 – Service Components

IPS – as an advanced server offering – supports multiple Internet standard protocols for its operation. The various protocols supported is implemented through a series of service components, one for each main protocol. Each defined service component has its own section in the site personality configuration file and you may have multiple services offering the same protocol support with different configurations within the same site personality as long as they are bound to different IP addresses and/or ports. All of these services has a set of common options as well as their own set of specific options. The common options are listed and described in the table below:

Parameter	Description	Default	Type
Address	IP address of the interface the service should bind its port to. Leave blank for it to bind to all available local addresses. The address should be specified as four decimal numbers separated with only a dot. If the admin and/or user accounts still has default passwords this setting is always forced to the localhost address (127.0.0.1).	Blank (Any address) unless admin and/or user accounts has default passwords.	Optional
Port	Port which this service should bind to and reply to connection attempts. Standard ports are best for most sites, but you may want to run services on other ports. Please keep in mind that many firewalls could block users for accessing services on non-standard ports.	Standard port for current Protocol setting: "21" – FTP "80" – HTTP "143" – IMAP "110" – POP "25" – SMTP	Optional
Protocol	What kind of protocol support will the service provide, possible choices are: "ftpd" – File Transfer Protocol "httpd" – HyperText Transfer Protocol "imap4d" – Internet Message Access Protocol "pop3d" – Post Office Protocol "smtpd" – Simple Mail Transfer Protocol	-	Required
ClientAddress	Which client addresses are allowed to access this service and which are not. Specify a list of address and/or FQDN masks to allow deny. The first matching mask is used. * and ? wild-chars may be used and ! in front reverses the effect and deny access to the clients matching this mask.	"!*"	Optional
DebugFlag	A number representing a bitmap of debug groups to enable for writing to the log file. Keep in mind that any debug logging is of limited use unless you are tracking down a problem and they will generate a lot of disk activity. Look for possible debug groups in the table below.	"0"	Optional
DisableReverse	Should every connections IP address be looked up in the DNS for logging and filtering purposes? If you disable these lookups you may for instance not use names as masks for the ClientAddress filtering.	"0" (False)	Optional
Host	The service name that the service will identify itself as to the client. This is should basically be the FQDN of the service you are hosting.	-	Required
LogFlag	A number representing a bitmap of log groups to skip when writing to the log file. Look for possible log groups in the table below.	"0"	Optional
Timeout	Time in seconds the connection can be inactive before it is closed.	"180" – FTP "300" – HTTP, POP and SMTP "1800" – IMAP	Optional
CacheMaxCount	The maximum number of documents in the dynamic document cache at any time. (minimum: 4)	"32"	Optional
CacheMaxSize	The maximum total size i kBytes of all the documents in the dynamic document cache at any time. (minimum: 64)	"1024"	Optional
ClientPool	How many client session should IPS keep in a ready-to-run status at any time. (range: 1-99)	"1" – ADMIN "8" – HTTP "4" – FTP, IMAP, POP and SMTP	Optional
ClientStack	Size in kBytes of the memory stack for each client session. This parameter should only be modified by advanced users running very special solutions. (range: 16-1024)	"128"	Optional
PoolFillFreq	How often in ms should IPS attempt to fill the client pool. (range: 50-30000)	"250"	Optional
hookOnPass	Path of Hook called when the password for a guest session is received. Hook should return 0 if okay, or a response to reject the log-in.	-	Optional
hookOnUser	Path of Hook called after a user name is received and a user file found. Hook should return 0 if log-in are okay, a response to reject.	-	Optional
SendBufferSize	Size in kBytes of the memory buffer used for sending or receiving data from clients between each disk I/O operation. (range:16-4096, maximum: CacheMaxSize / (CacheCount * 4)	"64"	Optional
MaxSessionsReject	Maximum number of sessions active before the system rejects new connections. New connections are rejected with information about the reason. A session is allocated to send the information.	“512”	Optional
MaxSessionsIgnore	Maximum number of sessions active before the system ignores new connections. New connection are dropped without any information to the client. No session is allocated to process the socket.	“1024”	Optional

LogLevel groups

The various values which make up a LogLevel setting for the various service types are listed in the table below:

LogLevel group¹	Description	FTP	HTTP²	IMAP	POP	SMTP
1	User authentication	USER PASS	Accepted connections Ended sessions	-	APOP USER PASS	HELO
2	-	APPE DELE RETR RNFR RNTO STOR	Rejected connections	-	DELE RETR	MAIL RCPT
4	-	CDUP CWD LIST MLSD NLST XCUP XCWD	-	-	LIST STAT	DATA
8	-	MKD RMD XMKD XRMD	-	-	RSET	RSET
16	-	MDTM MLST SIZE TYPE	-	-	-	-
32	-	PASV PORT TYPE	-	-	-	-
64	-	PWD SITE SYST XPWD	-	-	-	-
128	-	-	-	-	-	-
256	-	-	-	-	-	Remote delivery information
512	-	-	-	-	-	Local delivery information
1024	-	-	-	-	-	-
2048	-	-	-	-	-	Delivery error information
4096	-	-	-	-	-	-

¹Add together the values to make up a LogLevel setting.
²HTTP service components also supports standardized logging

DebugLevel groups

The table below lists the different DebugLevel values used to make up a DebugLevel setting:

DebugLevel groups¹	Description
1	Inbound data
2	Outbound data
4	Inbound buffer data
8	Outbound buffer data
16	System information data

¹Add together the values to make up a DebugLevel setting.

4.5.1 – FTP Component

The File Transfer Protocol (FTP) component was the basis of the first version of IPS, it is used to transfer any type of documents between any FTP capable client and/or other FTP capable servers controlled by the same FTP client (Typically called FXP).

In addition to the common component parameters the FTP component includes the parameters listed in the table below:

Parameter	Description	Default	Type
RootDirectory	Basic root directory of FTPd. This value may be overridden by the account value. (VFS format)	"/"	Optional
MaxUserBandwidth	Maximum retrieve bandwidth for each normal user session.	"0"	Optional
MaxAnonBandwidth	Maximum retrieve bandwidth for each guest session.	"0"	Optional
TimeoutMax	Maximum time-out allowed to set with the SITE IDLE command.	"300"	Optional
WelcomeFile	Path of welcome greeting shown to the user before login. (OS format)	-	Required
HideIfNoAccess	Hide files and directories which the user has no access to from directory listings.	"0" (False)	Optional
MinFreeSpace	The minimum number of MBytes free on the disk required to allow incoming files.	"512"	Optional
DisableEA	Disable EA access system. (OS/2 only)	"0" (False)	Optional
DisableDircount	Disable display of subdirectory count.	"0" (False)	Optional
PassiveAddressOverride	Override the IP address used in the replies to the PASV command. Mainly used if the service is behind a firewall not supporting FTP properly.	(Address)	Optional
PassivePortRangeOverride	Override the port range used for FTP passive mode. This take two decimal numbers separated with space. The first number is the starting port and the second number is the length of the range. Mainly used with the PassiveAddressOverride setting.	"16384 16384"	Optional
hookOnConnect	Path of Hook called when a user connects. Hook should return 0 if connection are okay, or a response if not.	-	Optional
hookOnCommand	Path of Hook called when each command is received before it is executed. Hook should return 0 or a changed command line.	-	Optional
hookOnRetr	Path of Hook called before a file is sent to the user. Hook should return 0 if the transfer are to proceed, and a response if it is rejected.	-	Optional
hookOnSite	Path of Hook called before executing internal SITE commands, this hook could return 0 to allow internal execution of the command or it could reject it by returning an alternative response.	-	Optional
hookOnStor	Path of Hook called before a file is received from the user. Hook should return 0 if the transfer are to proceed, and a response if it is rejected.	-	Optional

Component Access

Command	Task Description	Access	Restrictions
ABOR
APPE	(See STOR)
CDUP		--x
CWD		--x
DELE		rw-	--d
FEAT
HELP
LIST		--x	-l-
MDTM		r--
MLSD	(See LIST)
MLST		r--
MKD		-wx
MODE
NLST	(See LIST)
NOOP
OPTS
PASS
PASV
PORT
PWD
QUIT
REIN
REST
RETR		r--
RNFR		rw-	--d
RNTO		-w-
RMD		rwx	--d
SITE
SIZE		r--
STAT
STOR		-w-	--d
SYST
TYPE
USER
XCUP	(See CDUP)
XCWD	(See CWD)
XMKD	(See MKD)
XPWD	(See PWD)
XRMD	(See RMD)

4.5.2 – HTTP Component

The HyperText Transfer Protocol (HTTP) component is used to transfer hypertext documents between the server (IPS) and any HTTP capable client – typically a web browser. These documents are typically public – but they doesn't need to be – and are what makes up the world wide web today.

In addition to the common component parameters the HTTP component includes the parameters listed in the table below:

Parameter	Description	Default	Type
RootDirectory	Basic root directory of HTTPd. This value may be overridden by another RootDirectory entry matching the contents of Host header field sent by the client. (VFS format)	"/"	Optional
RootDirectory[<fqdn/ip>]	In addition to the default RootDirectory entry (the one above), you may specify any number of virtual RootDirectory entries used to point different web sites to other directories of the VFS tree. (VFS format) Examples ... RootDirectory=/html/site1 RootDirectory[www.mysite.com]=/html/site1 RootDirectory[www.othersite.com]=/html/site2 ... any requests without a proper Host header will be use the first entry, any request for www.mysite.com will always map to /html/site1 and any request for www.othersite.com will always map to /html/site2.	-	Optional
IndexFiles	Ordered list of index files for which IPS searches when a directory and no absolute file path is requested.	-	Optional
ApplicationDirectory	Default list of file extensions to be processed through an external application when requested. The action taken with the matching file are specified using the Application parameters. This value may be overridden by another ApplicationDirectory entry matching the current VFS directory the requested file resides in. Extensions should always be configured in lower case.	-	Optional
ApplicationDirectory[<vfs-dir>]	List of file extension used when the file requested is stored in the matching VFS directory. This list will override the default ApplicationDirectory extension list and you may have any number of these lines for the directories needed. Extensions and VFS directories should always be configured in lower case. Examples ... ApplicationDirectory=.php ApplicationDirectory[/cgi-bin]=.exe .bat ... any request to a file with the .php extension will be processed by the Application[.php] regardless of their location as long as they are not in the /cgi-bin directory. File with .exe or .bat extension in that directory will be processed according to their respective Application settings.	-	Optional
Application[<extension>]	Configuration about how to process a matching file. This is configured as a complete command line which is executed upon request of this file. The file path is automatically added at the end. Examples ... Application[.php]=php.exe Application[.cgi]=dll: ipsPlugin.dll Application[.bat]=cmd.exe /c ... will execute php.exe for any matching .php file, will call ipsPlugin.dll with any matching .cgi file and call cmd.exe with any matching .bat file.	-	Optional
ExtendedLogFile	Path of the optional extended log file. This file uses a standardized log file format configurable with the ExtendedLogFields parameter. (OS format) The use of this parameter is optional and it should be removed or commented if not in use.	-	Optional
ExtendedLogFields	Format of the standardized log file. Supported identifiers are: "x-common", "c-ip", "cs-method", "cs-uri", "sc-status", "date", "time", "time-taken", "bytes" and "cached".	-	Optional
FIBDirectory	List of file extensions for which FIB processing are enabled. This value may be overridden by another FIBDirectory setting matching the specific VFS directory housing the file.	-	Optional
FIBDirectory[<vfs-dir>]		-	Optional
SSIDirectory	List of file extensions for which SSI processing are enabled. This value may be overridden by another SSIDirectory setting matching the specific VFS directory housing the file.	-	Optional
SSIDirectory[<vfs-dir>]		-	Optional

4.5.3 – IMAP Component

The Internet Message Access Protocol (IMAP) component is still under development and will be included in later versions of IPS.

4.5.4 – POP Component

The Post Office Protocol (POP) component is exactly that – a post office. Messages received by IPS are stored in the users Inbox and the user can retrieve messages from this Inbox with any e-mail client using the POP protocol.

In addition to the common component parameters the POP component includes the parameters listed in the table below:

Parameter	Description	Default	Type
hookOnConnect	Path of Hook called when a user connects. Hook should return 0 if connection are okay, or a response if not.	-	Optional
hookOnCommand	Path of Hook called when each command is received before it is executed. Hook should return 0 or a changed command line.	-	Optional

4.5.5 – SMTP Component

The Simple Mail Transfer Protocol (SMTP) component is the basis of all e-mail delivery handled by IPS. It receives messages send by other mail servers to your users as well as send messages from your users to other SMTP servers on the Internet.

In addition to the common component parameters the SMTP component includes the parameters listed in the table below:

Parameter	Description	Default	Type
ForwardAddress	Like ClientAddress, but control the hosts allowed to forward messages through this server. It would be wise to restrict this to only known hosts to avoid becoming a spam relay server.	-	Required
ForwardAddressAuth	Works just like ForwardAddress, but is valid for authenticated clients only. If the remote client matches the main ForwardAddress setting it does not need to match this one.	*	Optional
ForwardDomains	List of domains for which this server allows forwarding messages to regardless of the client host.	-	Optional
ForwardToServer	If set, all outgoing messages will be forward to this server. IP address should be given, not a hostname.	-	Optional
QueueDirectory	Directory messages are queued in for sending. (OS format)	-	Required
QueueScanFreq	How often in seconds should IPS scan the e-mail queue for message to be delivered. (range: 30-900)	"60"	Optional
LocalDomain	Main e-mail domain hosted by this server.	-	Required
LocalDomains	List of domains which are locally handled by this server. Example ... LocalDomains=@iq.to @inetpowerserver.com ... configures IPS to accept messages for these two domains and deliver them to the local mailboxes.	-	Required
CatchAllIdent	Name of account which catch all messages to otherwise unknown users.	-	Optional
ConnectRetries	Maximum number of connection attempts to a remote mail server before giving up.	"5"	Optional
ConnectRetryDelay	Minimum time in minutes to wait before another connection attempt is made.	"30"	Optional
LookupRetries	Maximum number of DNS lookup attempts performed to find a remote mail server before giving up.	"5"	Optional
LookupRetryDelay	Minimum time in minutes to wait before another lookup attempt is made.	"5"	Optional
MessageAgeMax	Maximum age in minutes of any message in the delivery queue.	"7200"	Optional
BindOnDelivery	Shall we attempt to bind to the SMTP port for outbound delivery?	"0"	Optional
hookOnConnect	Path of hook called when a user connects. Hook should return 0 if connection are okay, or a response if not.	-	Optional
hookOnCommand	Path of hook called when each command is received before it is executed. Hook should return 0 or a changed command line.	-	Optional
hookOnData	Path of hook called when a new message body is received but before any further delivery is done. Hook should return 0 to accept the queuing of the message or a valid response to reject the message.	-	Optional
hookOnDelivery	Path of hook called whenever a message delivery stage is about to be entered.	-	Optional
hookOnHelo	Path of hook 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.	-	Optional
hookOnMail	Path of hook 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”.	-	Optional
hookOnRcpt	Path of hook 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.	-	Optional

4.6 – Service Responses

When a client requests service from IPS or any other server, both the client and server engage in a dialog of conversation. The responses that IPS provides are done in accordance to the appropriate RFC, but can be modified in every aspect. It is recommended, however, that only experienced IPS administrators make these changes.

Each response message can be made up of one or more lines (where applicable), and IPS's variables can be referenced within these messages in order to facilitate the need for tailored output. Note that the messages (ie: FTP messages) as seen by the user can be changed, as can the associated numeric codes. These codes are what the client software interprets, and (again in the case of FTP and mail clients as well) the text messages are usually forwarded by the client software to the log or "view" of that client software for viewing by the user. This section will illustrate how to configure the messages that IPS provides to connected clients.

Response messages for each of the services IPS provides are stored in specific subdirectories under .\messages\<protocol-type>, having the extension ".res". Files with the extension ".msg" are straight text files used to display multi-lined messages for responses.

Responses come in the form of single lines in .res and entire files themselves. FiBs (Fill in the Blanks) are applicable to single-line response files and multiple-line .msg files too, so system variables can be, and are parsed into the displayed text where specified.

Please refer to the following text files as examples, which are included as part of the IPS distribution in .\messages\ftp:

login.msg - displayed to users immediately following login.
login-anon.msg - showed to anonymous users immediately following login
retr0.msg - displayed after successful download, showing transfer stats
sitestat.msg - user's current site statistics
stor0.msg - displayed after a successful upload, showing transfer stats
welcome.msg – not included in the distribution, but will be displayed before the login prompt if it exists.

Note that FiBs and system variables are used frequently throughout these files.

4.6.1 – Enhanced Response Messages

In addition to the basic response messages you may send the contents of text files or even execute a script which provides the needed response. These features are best explained looking at an example.

First let us look at the following extract from the FTP response file:

messages\ftp\ftp.res

[RETR]
226a=226 File transfer complete.
226A=messages\ftp\retr1.msg

This is actually the "magic" which displays the file transfer statistics to the FTP client whenever a file is downloaded from the server. As you see here we have the first "226a" line which is the basic response, in addition we also have the "226A" (note the capital "A") which points to the file displayed to the client. We also see that there is used FiBs expression with the variable "usr.anon" here. That means that it will resolve to "retr0.msg" if the users is non anonymous and "retr1.msg" if it is an anonymous user. If you open the shipped file in any text editor you will see that a lot of FiBs are used within the file as well.

To bring this further you can even specify the path to a REXX script with the ".rexx" extension and that script will be executed using the IPS RexxHook engine. The script should then send the appropriate response using the IPSSAY command from within REXX.

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