REFERENCE GUIDEdocs.smoe.org/openwave/Kx4.2/Kx42ref.pdfThis manual is organized as follows: • Chapter 1, System Overview, provides an overview of the InterMail Mx system. • Chapter

R E F E R E N C E G U I D E

Version 4.2Published November, 1999

Software.com, Inc.

www.software.com

525 Anacapa Street 10 Maguire Road, Suite 400Santa Barbara, CA 93101-1603 Lexington, MA 02421-3130Tel: (805) 882-2470 Tel: (781) 274-7000Fax: (805) 882-2473 Fax: (781) 674-1080

The InterMail software is a copyrighted work of Software.com, Inc. © 1993–1999 Software.com, Inc. All rights reserved.

InterMail includes software that is copyright © 1990, 1993, 1994, The Regents of the University of California. All rights reserved. This code is derived from software contributed to Berkeley by Mike Olson.

SmartHeap, portions copyright © 1991–1997, Compuware Corporation.

InterMail incorporates a derivative work of the SSL Plus: SSL 3.0 Integration Suite Toolkit, copyright © 1996, 1997, Consensus Development Corporation. SSL Plus: SSL 3.0 Integration Suite is a trademark of Consensus Development Corporation, which reserves all rights thereto.

Portions of the SSL Plus: SSL 3.0 Integration Suite Toolkit software are based on SSLRef™3.0, which is copyright © 1996, Netscape Communications Corporation. SSLRef™ was developed by Netscape Communications Corporation and Consensus Development Corporation.

The MD5 Message-Digest algorithm used in InterMail is a copyrighted work of RSA Data Security, Inc., copyright© 1991–1992, RSA Data Security, Inc. All rights reserved.

InterMail incorporates a derivative work of the BSAFE cryptographic toolkit, copyright © 1992–1996, RSA Data Security, Inc. All rights reserved.

BSAFE is a trademark of RSA Data Security, Inc.

The RSA Public Key Cryptosystem is protected by U.S. Patent #4,405,829.

The Regular Expression Routines used in InterMail are copyright © 1992–94, Henry Spencer. All rights reserved. This software is not subject to any license of the American Telephone and Telegraph Company or of the Regents of the University of California.

The InterMail LDAP code is derived from software that is copyright © 1992–1996 Regents of the University of Michigan. All rights reserved. Redistribution and use in source and binary forms are permitted provided that this notice is preserved and that due credit is given to the University of Michigan at Ann Arbor. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. This software is provided “as is” without express or implied warranty.

The InterMail Kx Reference Guide, Version 4.2, is a copyrighted work of Software.com, Inc.© 1997–1999, Software.com, Inc. All rights reserved.

No part of this documentation may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than personal use, without the express written permission of Software.com, Inc.

This copyrighted work contains trade secret information of Software.com, Inc. Use, transfer, disclosure, or copying without the express written permission of Software.com, Inc., is strictly forbidden. Information in this document is subject to change without notice and does not represent a commitment on the part of Software.com, Inc.

INTERMAIL, SOFTWARE.COM, and SOFTWARE.COM THE INTERNET INFRASTRUCTURE COMPANY are registered trademarks, and POST.OFFICE and WEBEDGE are trademarks, of Software.com, Inc. and are registered trademarks in various countries around the world.

NETSCAPE is a registered trademark of Netscape Communications Corporation.

OPENVIEW is a registered trademark of Hewlett-Packard Company.

WINDOWS NT is a registered trademark of Microsoft Corporation.

SQL*NET is a trademark and ORACLE is a registered trademark of Oracle Corporation.

SUN is a registered trademark of Sun Microsystems, Inc.

VERITAS is a registered trademark of Veritas Software Corporation.

Other product, brand, and company names mentioned herein may be trademarks, registered trademarks, or service marks of their respective holders.

InterMail Kx Reference Guide, Version 4.2

Document number: KR-991110

Confidential and Proprietary, © Software.com, Inc. 1999 iii

Table of Contents

Preface .......................................................................................................... vii

1: System Overview ....................................................................................... 1InterMail Servers..................................................................................................................1InterMail Data Storage.........................................................................................................2Message Flow Through the InterMail System.....................................................................2

2: Configuration Keys.................................................................................... 5Sample Configuration Key...................................................................................................5

InterMail Servers and Processes....................................................................................6Impact of Configuration Key Changes..........................................................................8

InterMail Configuration Keys..............................................................................................8

3: Directory Management Utilities ............................................................ 207imdbcontrol ......................................................................................................................207

imdbcontrol Syntax ...................................................................................................208Available imdbcontrol Operations ............................................................................209Domain Operations....................................................................................................211CreateDomain (cd) ....................................................................................................211Account Operations ...................................................................................................216Mail Delivery Operations ..........................................................................................231SMTP Alias Operations.............................................................................................235Class-of-Service Operations......................................................................................237

imbatchextract ..................................................................................................................242imbatchextract Syntax ...............................................................................................242Creating a Targeted User Batch File .........................................................................244

imbatchload......................................................................................................................244imbatchload Syntax ...................................................................................................244imbatchload Input File...............................................................................................245Input File Record Types ............................................................................................247

imintegcheck ....................................................................................................................251 imintegcheck Syntax ................................................................................................252imintegcheck Operations ...........................................................................................252

ldapadd .............................................................................................................................253ldapdelete .........................................................................................................................254ldapmodify .......................................................................................................................255ldapmodrdn ......................................................................................................................256ldapsearch.........................................................................................................................257

4: General Administration Utilities ........................................................... 259Command Descriptions....................................................................................................259

5: InterMail C API........................................................................................ 295Introduction......................................................................................................................295Naming Conventions........................................................................................................295

InterMail Kx Reference Guide

iv Confidential and Proprietary, © Software.com, Inc. 1999

Function Semantics ..........................................................................................................296Calling Conventions.........................................................................................................296

Library Initialization..................................................................................................296Object Data Types .....................................................................................................297

Overview of Types...........................................................................................................298Errors................................................................................................................................299String Arrays ....................................................................................................................301Domains ...........................................................................................................................301Accounts...........................................................................................................................305Mailboxes.........................................................................................................................315Folders..............................................................................................................................317Messages ..........................................................................................................................320Reply ................................................................................................................................323Class of Service................................................................................................................325Configuration Information ...............................................................................................329MIME Information...........................................................................................................330Log Messages...................................................................................................................335Log Context......................................................................................................................337Compiling, Linking, and Running ...................................................................................340

Sun Microsystems Solaris 2.5.1 and 2.6....................................................................340Digital UNIX.............................................................................................................341Silicon Graphics IRIX 6 ............................................................................................341

File Summary...................................................................................................................341Function Summary...........................................................................................................342

6: InterMail Perl API ................................................................................... 347Introduction......................................................................................................................347

General Usage Notes .................................................................................................348Hooking Classes in Your Scripts...............................................................................348Underlying Libraries and Versioning........................................................................349Error Handling...........................................................................................................350Classes and Objects ...................................................................................................350

SwCom::Error Class Reference .......................................................................................352SwCom::WebSession Class Reference............................................................................352SwCom::Mail Class Reference ........................................................................................354

CosAttribute ..............................................................................................................354Cos.............................................................................................................................356Domain ......................................................................................................................359Account......................................................................................................................363Mailbox......................................................................................................................373Folder.........................................................................................................................377Message .....................................................................................................................381Reply..........................................................................................................................385ConfigItem.................................................................................................................387MimeInfo...................................................................................................................388LogMsg......................................................................................................................390LogContext ................................................................................................................391

Table of Contents

Confidential and Proprietary, © Software.com, Inc. 1999 v

7: InterManager Perl API............................................................................ 393Introduction......................................................................................................................393Overview of Classes.........................................................................................................393InterManager Perl API Classes ........................................................................................394

SwCom::Error............................................................................................................394SwCom::WebSession ................................................................................................395SwCom::IMgr::Session .............................................................................................396SwCom::IMgr::Entry.................................................................................................398SwCom::IMgr::Root..................................................................................................401SwCom::IMgr::Org ...................................................................................................401SwCom::IMgr::OrgUnit ............................................................................................405SwCom::IMgr::Person...............................................................................................408SwCom::IMgr::MailGroup........................................................................................413SwCom::IMgr::MailTemplate...................................................................................416SwCom::IMgr::MailCOS ..........................................................................................418SwCom::IMgr::Provider............................................................................................421SwCom::IMgr::AdminGroup ....................................................................................424SwCom::IMgr::Domain.............................................................................................425

8: LDAP Perl API ........................................................................................ 427Error-Processing Function ...............................................................................................428

ldap_err2string(rc) .....................................................................................................428Connection Management Functions.................................................................................428

ldap_open(host, port).................................................................................................428ldap_simple_ bind_s(ld, login, password).................................................................428ldap_unbind(ld) .........................................................................................................429

Functions That Perform Operations on Entries................................................................429ldap_add_s(ld, dn, data) ............................................................................................429ldap_modify_s(ln,dn, data)........................................................................................430ldap_delete_s(ld, dn) .................................................................................................430ldap_modrdn_s(ld, dn, newrdn) ................................................................................431ldap_rename_s(ld, dn, newrdn, newbase, deleteold).................................................431ldap_search_s(ld, dn, scope, filter, attrs, attrsonly, result) ........................................432ldap_count_entries(ld, result) ....................................................................................432ldap_get_all_entries(ld, result) ..................................................................................433

Access Control Information Function..............................................................................433ldap_apply_aci_rule_s...............................................................................................433

Memory Management Function.......................................................................................434ldap_msgfree(result)..................................................................................................434

9: Log Events.............................................................................................. 435Account Log Events.........................................................................................................436Configuration Log Events................................................................................................447Database Log Events........................................................................................................469Directory Cache Log Events ............................................................................................483Filter Log Events..............................................................................................................483File Input/Output Log Events ..........................................................................................487IMAP Log Events ............................................................................................................502


vi Confidential and Proprietary, © Software.com, Inc. 1999

LDAP Log Events............................................................................................................508Message Store Log Events...............................................................................................533Message (Mail) Log Events .............................................................................................558MTA Log Events .............................................................................................................570Network Input/Output Log Events...................................................................................592Parameter Log Events ......................................................................................................609POP Server Log Events....................................................................................................610Process Log Events ..........................................................................................................616RME Log Events..............................................................................................................653Remote Control Server Log Events .................................................................................662SMTP Log Events............................................................................................................668SSL Log Events ...............................................................................................................688System Log Events...........................................................................................................690

A: Configuration Keys by Server.............................................................. 693Common Configuration Keys ..........................................................................................693MTA Configuration Keys ................................................................................................695MSS Configuration Keys .................................................................................................700Directory Server Configuration Keys ..............................................................................702POP Server Configuration Keys ......................................................................................703IMAP Server Configuration Keys....................................................................................704Configuration Server Configuration Keys .......................................................................705Manager Server Configuration Keys ...............................................................................705SNMP Server Configuration Keys...................................................................................705

B: Supported RFCs.................................................................................... 707

C: License Information .............................................................................. 709

Glossary...................................................................................................... 717

Index............................................................................................................ 739

Confidential and Proprietary, © Software.com, Inc. 1999 vii

Preface

Welcome to InterMail Kx!

The InterMail Kx Reference Guide contains background information about the InterMail servers and databases, configuration keys, directory management utilities, administrative utilities, APIs, and event messages.

Intended AudienceThis guide assumes that you have a technical background as well as a working knowledge of the Internet and high-end system issues.

OrganizationThis manual is organized as follows:

• Chapter 1, System Overview, provides an overview of the InterMail Mx system.

• Chapter 2, Configuration Keys, describes all InterMail Kx configuration keys, which specify security features, port configurations, auto-reply messages, and other InterMail settings and behaviors.

• Chapter 3, Directory Management Utilities, describes all InterMail directory management commands.

• Chapter 4, General Administration Utilities, describes all InterMail administration commands.

• Chapter 5, InterMail C API, describes the C API library available for creating programs that access data in the ISD and MSS databases.

• Chapter 6, InterMail Perl API, describes the InterMail Perl API (SwCom::Mail).

• Chapter 7, InterManager Perl API, provides descriptions of the InterManager Perl API classes.

• Chapter 8, LDAP Perl API, describes the modifications made by Software.Com to the standard LDAP Perl API.

• Chapter 9, Log Events, provides a listing of all InterMail log events.

• Appendix A, Configuration Keys by Server, groups configuration keys according to the servers they control.


viii Confidential and Proprietary, © Software.com, Inc. 1999

• Appendix B, Supported RFCs, lists the Internet mail standards that InterMial complies with.

Conventions

Convention Description Example

$ at the start of a string An environment variable (set at the time of installation)

$spoolDir

monospace type • Commands

• Directory and file names

• Hostnames

• Configuration keys and their values

• Utility names

imdbcontrol command

cron utility

Set this key to true.

<angle brackets> in a command

A required variable imboxget <address>

[square brackets] in a command

An optional parameter imctrl [-verbose]

| (a vertical bar) between options in a command

Exclusive options, of which you can use only one

impwdhash -a [md5-po|unix]

{braces} around options in a command

A list of options, one of which is required

immsgdelete {<msgID>...|-all}

... (an ellipsis) after an optional entry in a command

An option for which you may have multiple entries

imbucketscreate [<c1...cn>]

boldface in an example User input venus% imservctrl stop

Preface

Confidential and Proprietary, © Software.com, Inc. 1999 ix

Related DocumentationThis manual is one of a set. Other manuals in this set are:

• InterMail Kx Operations Guide, which provides instructions for the operation and administration of the InterMail system.

• InterMail Kx Installation Guide, which provides instructions for installing InterMail.

• InterMail Kx Migration Guide, which provides instructions for migrating to InterMail from the SendMail or Post.Office messaging product.

Questions and CommentsYour feedback is important to us! To suggest improvements or make comments on the content of this manual, please send e-mail to [email protected].


x Confidential and Proprietary, © Software.com, Inc. 1999

Confidential and Proprietary, © Software.com, Inc. 1999 1

1System Overview

This chapter provides an overview of InterMail system architecture. It includes the following topics:

• An introduction to the InterMail servers and associated databases

• An explanation of how messages flow through the system

InterMail ServersThe InterMail system consists of nine servers. The servers that play a direct role in message processing are as follows:

• The Message Transport Agent (MTA) receives all incoming messages and redirects them to the appropriate location.

– Mail destined for local users is passed to the Message Store Server.

– Mail destined for remote users is passed to the appropriate remote mail server.

– Mail that contains addressing errors or appears to be spam is held for administrator review.

Note: The MTA provides temporary storage for messages that cannot be delivered immediately. It re-attempts delivery of those messages on a periodic basis until they are successfully transmitted.

• The Message Store Server (MSS) manages the mailboxes for local users. The MSS takes delivery of messages from the MTA and services requests for message retrieval from the POP, IMAP, and Web servers.

• The POP server services requests for message retrieval from any client that supports the POP3 protocol.

• The IMAP server handles requests for message retrieval from any client that supports the IMAPv4 protocol.


2 Confidential and Proprietary, © Software.com, Inc. 1999

• The Web server allows end users to retrieve mail using a Web browser and WebEdge.

• The Directory server responds to requests from the MTA, the POP server, the IMAP server, and the Web server. It replies with information about accounts, domains, and classes of service. The response provided by the Directory Server indicates if a user has a local mailbox and if additional mail delivery operations (mail forwarding or automatic replies) are required.

The remaining three InterMail servers provide general management of the system:

• The Configuration server responds to requests to set, change, or display configuration options that control the behavior of each InterMail server.

• The Manager server is used to start and stop all InterMail servers.

• The SNMP server allows administrators to monitor a variety of server behavior and view the information in real-time, without having to develop scripts or parse logs. The SNMP Server interacts with standard SNMP clients, such as HP OpenView.

InterMail Data StorageThe InterMail system maintains required data in the following four locations:

• The Message Store database, which contains information about mailboxes, folders, message headers, and message status (read or unread, for example). Among the entries in the Message Store database are pointers to the location of the actual message files.

• The Message File system, which stores the messages themselves (headers, bodies, and any attachments) as individual files.

Note: Messages destined for multiple recipients are stored only once in the Message File system, thus conserving valuable system resources.

• The Directory database, which stores users’ account information and information about domains known to the system, as well as class-of-service definitions and organizational information required to support delegated administration. For a full discussion of directory data, see Chapter 4 of the InterMail Kx Operations Guide.

• The Configuration database contains entries that govern the behavior of the various InterMail servers. For a complete listing of InterMail configuration options, see Chapter 2 of this manual. For instructions on editing the content of the Configuration database, see Chapter 7 of the InterMail Kx Operations Guide.

Message Flow Through the InterMail SystemThe individual InterMail components work together to facilitate mail delivery and retrieval.

System Overview


Figure 1 illustrates message and communications flow through a sample InterMail system. The large rectangle represents the InterMail host machine. Solid lines represent message flow. Broken lines indicate communication between system components.

Note: The servers dedicated to managing the InterMail system do not appear in this diagram since they do not play a direct role in message flow.c

Figure 1 Message and communication flow in InterMail

1. All incoming messages, whether from a local client or another mail server, arrive at the designated SMTP port (typically, port 25). The MTA listens at this port and accepts messages into the system for processing.

2. The MTA is responsible for initial mail screening, performing tasks such as dropping connections or blocking mail from unauthorized senders. Once the MTA accepts a message, it determines whether the message’s destination is a local mailbox or a remote mail server.

If the message is addressed to a user in an unknown domain, the MTA obtains the location of the responsible mail server and passes the message to that server.

3. If the message is addressed to a user in a known domain, the MTA contacts the Directory server and requests the location of the user’s mailbox.

4. Once it has the required account information, the MTA establishes a connection (if one does not already exist) with the Message Store Server (MSS) and sends a request to open the user’s mailbox. The MTA then passes the message to the MSS, which inserts it in the appropriate mailbox.

5. The MTA typically handles the entire delivery transaction in memory, without writing anything to disk. However, if any of the following is true of the message, the MTA secures the message by writing it to a temporary storage area known as the spool directory, and then proceeds with mail processing:

– The message has more than more than a specified number of recipients.

– The message will take longer than a specified time to deliver.

– The message is larger than a specified size.

– The message is suspected of being junk mail.

– The message has an error that makes it undeliverable.

– The message is destined for a server that is temporarily unavailable.

6. The MSS is responsible for storing the message data sent by the MTA. Upon receiving a new message, the MSS writes information to both the Message Store database and the Message File system. Part of the information written to the Message Store database is a pointer to the location of the message file in the Message File system.

Web ServerIMAP ServerPOP Server

WebMail ClientIMAP ClientPOP Client

POP port 110 IMAP port 143 HTTP port 80

107

8

10107 7



Only after successful completion of these operations does the MSS signal acceptance of the message to the MTA. At this point, the MTA is free to delete any temporary files and signal acceptance of the message to the sending server.

Note: To prevent message loss, the MTA will not signal acceptance of a message to the sending agent until either delivery is successful or the message data is safely stored in the spool directory.

7. Local users request message retrieval with a POP, IMAP, or WebEdge client. Each client contacts the appropriate server on the designated port (port 110 for POP transactions, port 143 for IMAP transactions, or port 80 for HTTP transactions) and transmits the user’s login name and password.

8. The POP, IMAP, or Web server listening on the designated port forwards the user’s name and password to the Directory server for validation. The Directory server checks the user’s account information to authenticate the password, and (assuming the password is valid) replies with the user’s mailbox name and location.

9. The POP, IMAP, or Web server connects with the MSS, requests access to the appropriate mailbox, and begins working between the client and the MSS to process the user’s requests.

10. POP users download their messages to a local machine. IMAP users either download their messages to a local machine, or work with them directly on the InterMail host. WebEdge users read their messages directly from their mailboxes on the host machine.


2Configuration Keys

You can customize the behavior of InterMail servers and utilities using the configuration keys this chapter describes. The keys appear alphabetically, with a table of information about each key.

Note: For a complete discussion of configuration management and instructions on changing configuration keys, see Chapter 7 of the InterMail Kx Operations Guide.

This chapter contains the following:

• A sample configuration key description, with an explanation of terminology

• An alphabetical listing of all InterMail configuration keys

Sample Configuration KeyThe table for the fictional configuration key configKeyName introduces the table format and terminology used throughout this chapter.

Note: Although multi-word keys appear written in both upper and lowercase, this is solely for the sake of readability. All configuration keys are case-insensitive.



��

InterMail Servers and ProcessesEach InterMail server has a corresponding process name. Unless otherwise indicated, the syntax for each configuration key must include the appropriate server process name. For example, in the following key the client timeout period on the IMAP server (imapserv) is set to 1800 seconds:

/*/imapserv/clientTimeout: [1800]

Description: Explains the purpose of the key, describes the format of key entries, and provides suggested settings where appropriate.

Related Keys: Lists additional configuration keys (if any) that work together with this key to achieve a specific result.

Servers Affected: Indicates the InterMail servers that this key affects. (See Section for a list of InterMail servers and associated processes.)

Change Impact: Describes the implications of changing the value of a particular configuration key. The possible impacts are:

• Server restart required

• Trivial, no server restart required

• No impact on server

Possible Values: Describes the allowable values for a key, such as, true or false, a text string, an integer, and so forth.

Initial Value: Defines the entry for a configuration key initially set during InterMail installation.

Default Value: Specifies the value the system inserts if there is no explicit value set for this particular key.

If several servers use the same configuration key, there may be different default settings for each server.

Null designates the absence of a value.

Example: Sample syntax for the key, including the complete configuration hierarchy, the key name, a colon, a space, and the value of the key enclosed in square brackets. For example:

/*/mta/configKeyName: [true]

Configuration Keys


The InterMail servers and their corresponding server process names are as follows:

You may also use the sysadmin module in place of the server process name for certain configuration settings. When this is the case, the example indicates it clearly.

Common server configuration

Some configuration keys can define settings for more than one server at a time. Where indicated, you can use common in place of the server process name to use a single setting to configure every server affected by this particular key.

For example, the badPasswordDelay key, which sets the number of seconds for which a bad password delays subsequent authentication attempts, can apply to both the POP and IMAP servers. You can define the delay for both servers with a single command, by using common in place of the process name, as follows:

/*/common/badPasswordDelay: [5]

Individual server configuration

If there is a requirement to have different delay periods for the POP and IMAP servers, set them independently, as follows:

/*/popserv/badPasswordDelay: [5]/*/imapserv/badPasswordDelay: [8]

Server Name: Server Process Name:

MTA (Message Transport Agent) mta

MSS (Message Store Server) mss

POP server popserv

IMAP server imapserv

Directory server (the server portion of the Integrated Services Directory)

imdirserv

Configuration server imconfserv

Manager server immgserv

SNMP server snmpdm



Impact of Configuration Key ChangesThe Change Impact section of the configuration key table describes the implications of changing the value of a particular configuration key. The possible impacts are:

• Server restart required—You must restart the server for the change you made to take effect. The server can read the new setting only at startup time. The server does not restart automatically; you must restart it.

• Trivial, no server restart required—The server will be able to read the new configuration setting the next time it is necessary without having to be restarted first.

• No impact on server—Changing the value of the configuration key affects something other than a server, typically a utility that retrieves the new value the next time it runs.

InterMail Configuration KeysThe following is a list of all configuration keys that can be set in the configuration database (config.db).

Warning! Certain configuration keys in this section allow you to specify a single IP address or a list of IP addresses. When specifying IP addresses as values for these keys, be aware that 0 signifies a wildcard. For example, specifying 0.0.0.0 as a value for the relaySourceRemoteIPList allows anyone to relay.0.0.0.0 is not a valid alias for the local host, and it should not be used as such. 127.0.0.1 should always be used instead.

Configuration Keys


��

��

Description: Command line options for the InterMail server that the <server> variable identifies.

The imservctrl command invokes the options listed in this key.

Note: System administration keys, such as <server>_opt, are in the configuration hierarchy under the path /<host>/sysadmin/.

Related Keys: none

Servers Affected: all servers

Change Impact: Warning! Do not attempt to modify the value of this key.

Possible Values: any command line options that are valid for the <server> indicated

Initial Value: set during installation

Default Value: null

Example: /paris/sysadmin/mss_opt: [-db]

Description: Indicates whether the InterMail server that <server> identifies runs on a particular host.

imservctrl uses this key when deciding which servers it should start up or shut down on each host.

Note: System administration keys, such as <server>_opt, are in the configuration hierarchy under the path /<host>/sysadmin/.

Related Keys: none



Possible Values: on or off


Default Value: off

Example: /paris/sysadmin/mta_run: [on]



��

��

Description: Indicates whether servers should abort if they are unable to write to their log file. If true and a server is unable to log its activity, the server will stop running. If false and logging fails, the servers keep running and the standard operating system log file records an error. To maximize system availability, it is advisable that you disable this option by setting abortIfLogFails to false.

Related Keys: none


Change Impact: server restart required

Possible Values: true or false

Initial Value: false

Default Value: false

Example: /*/common/abortIfLogFails: [false]

Description: Name of the administrative mailbox. Each Message Store Database contains an administrative mailbox that stores the “welcome” message and other special messages. All messages in the administrative mailbox are exempt from the absolute limit on message lifetimes, which means that they can remain in the mailbox indefinitely.

Related Keys: none

Servers Affected: MSS

Change Impact: no impact on server

Possible Values: a text string

Initial Value: admin

Default Value: admin

Example: /*/mss/adminMessageStoreName: [admin]

Configuration Keys


��

��

Description: Port on which an InterMail server listens for special instructions (for example, requests to shut down or return its version number).

adminPort must be unique for every server on a given host. However, to prevent the possibility of port conflict, it is advisable that adminPort be unique for every server in your entire InterMail installation.

Related Keys: none



Possible Values: any valid, unused port number


Default Value: null

Example: /paris/imconfserv/adminPort: [5001]

Description: Indicates whether the system sends InterMail product identification with the MTA’s standard 220 greeting response.

When true (the default setting), the MTA responds to connections on the SMTP port with a 220 greeting that includes information identifying InterMail as the mail system software. This includes both the name and version number of the product.

If you wish to hide the identity of your mail system software, disable this option by setting advertiseProduct to false.

Related Keys: none

Servers Affected: MTA

Change Impact: trivial, no server restart required


Initial Value: true

Default Value: true

Example: /*/mta/advertiseProduct: [true]



��

��

Description: Provides a list of addresses in CIDR notation [x.x.x.x/x] that are allowed to connect to the POP server. Those that cannot connect are instantly dropped. If the list is empty, or the configuration key is not present, there are no restrictions on connections.

Related Keys: none

Servers Affected: POP server

Change Impact: Trivial, no server restart required

Possible Values: list of entries, or null

Initial Value: null

Default Value: null

Example: /*/popserv/allowedIPs: []

Description: Enables/disables support for the SMTP command ETRN, which requests immediate processing of queued mail for a particular domain.

If true, the system accepts ETRN requests and attempts to process queued mail for the specified domain.

If false, the system does not allow ETRN requests.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/allowEtrn: [true]

Configuration Keys


�� !��

��"��

Description: Enables/disables support for the SMTP command EXPN, which “expands” an alias or mailing list address to determine the addresses to which it forwards mail.

If true, the system responds to EXPN requests with expanded account information.

If false, the system does not allow EXPN requests.

To maintain system security at the highest level, it is advisable that allowExpn be false.

Related Keys: none






Example: /*/mta/allowExpn: [false]

Description: Enables/disables support for the SMTP command HELP, which provides a list of the SMTP commands that your mail server supports.

If is true, the system responds to Help requests with a list of supported SMTP commands.

If false, the system does not allow HELP requests.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/allowHelp: [true]



��#��

��$��

Description: Enables/disables support for the QSND command, which requests immediate processing of queued mail for a particular host or for all hosts.

If true, the system accepts QSND requests and attempts to process the queue.

If false, the system does not allow QSND requests.

Note: The QSND command originated before the SMTP command ETRN (see the allowEtrn configuration key for a description). It is a proprietary queue-processing command that remains supported for backward compatibility.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/allowQsnd: [true]

Description: Specifies whether or not TLS is allowed by the MTA (the ESMTP keyword for TLS is STARTTLS, so this is really whether the STARTTLS keyword is allowed or not).

Related Keys: none



Possible Values: false or true



Example: /*/mta/allowTLS:[false]

Configuration Keys


��%��

Description: Enables/disables support for the SMTP command VRFY, which verifies that the server recognizes the intended recipient before sending a message.

If true, the system responds to VRFY requests by indicating whether the recipient is known or unknown.

If false, the system does not allow VRFY requests.

Note: SMTP clients do not commonly use the VRFY command. It is most frequently a tool for debugging mail delivery problems.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/allowVrfy: [true]



��#��

Description: Indicates whether to queue all outgoing messages whether or not a queue already exists for the destination host.

When true, the system never attempts immediate delivery of outgoing mail. Instead, the system queues all outgoing messages and attempts delivery at the next queue-processing interval.

When false, the system attempts to deliver outgoing mail immediately, unless mail is already queuing for the host to which a particular message is going. If mail is already queuing for a destination host, messages addressed to that host join the queue to await delivery at the next queue-processing interval (as outboundDeferProcessInterval defines).

A setting of true can delay mail delivery, so setting the value to false is advisable.

Related Keys: none






Example: /*/mta/alwaysQueue: [false]

Configuration Keys


��$��

Description: Indicates whether or not immediate mail delivery should be attempted for domains that are already queuing mail.

In standard InterMail operation, if a queue already exists for a particular domain, subsequent mail that arrives for that domain is automatically added to the queue, with delivery re-attempted at intervals defined by the value of the outboundDeferProcessInverval configuration key. This behavior can be altered by using the alwaysTryFirst and alwaysTryFirstList configuration keys.

There are four possible settings for the alwaysTryFirst configuration key. The first two, false and true, affect all domains that are queuing mail. The other two settings, allowlisted and denylisted, affect only a limited set of domains, those listed in the alwaysTryFirstList configuration key. The settings and their effect on system behavior are as follows:

• If the value of alwaysTryFirst is set to false , InterMail will never attempt immediate delivery of a message destined for any domain that is already queuing mail. Instead, addi-tional messages for such domains will be added to the existing queues and held until the next deferred mail processing inter-val. Use of this setting conserves system resources by limiting delivery attempts to domains whose mail host may be tempo-rarily out of service.

• If the value of alwaysTryFirst is set to true, InterMail will always attempt immediate message delivery of all mes-sages. A message will be added to a queue only after Inter-Mail learns that the mail host for the desired domain is unavailable.

• If the value of alwaysTryFirst is set to allowlisted, the system can accommodate immediate delivery to a specified subset of the domains that are queuing mail. If the domain to which the message is addressed is listed among the entries in the alwaysTryFirstList configuration key, delivery will be attempted immediately regardless of queuing status. How-ever, if mail is already queuing for a domain and that domain name is not listed among the values for the alwaysTry-FirstList key, InterMail will simply add the message to the existing queue without attempting immediate delivery.



• If the value of alwaysTryFirst is set to denylisted, the system can accommodate immediate delivery to most domains while denying this option to a specified subset of the domains that are already queuing mail. If mail is already queued for the domain to which the message is addressed and the name of that domain appears among the values for the alwaysTryFirstList key, InterMail will simply add the message to the existing queue without attempting immediate delivery. For all other messages, delivery will be attempted immediately.

Note: The alwaysQueue configuration key takes precedence over the alwaysTryFirst key. If the alwaysQueue configuration key is set to true, the value in alwaysTryFirst will be ignored.

Related Keys: alwaysTryFirstList



Possible Values: true, false, allowlisted, denylisted



Example: /*/mta/alwaysTryFirst: [allowlisted]

Configuration Keys


��$��

Description: Specifies a list of domains for which the system will allow or disallow immediate delivery attempts (when mail is already queued for these domains). Multiple entries are allowed, however each listed domain must appear on its own line, between its own set of square brackets.

This key works in conjunction with the alwaysTryFirst configuration key. If alwaysTryFirst is set to allowlisted, then InterMail will always attempt immediate delivery for messages addressed to any domain in this list, even if mail is already queued for that domain. If alwaysTryFirst is set to denylisted, then InterMail will never attempt immediate delivery for messages addressed to any domain in this list if that domain is already queuing mail. Instead, new messages will simply be added to the domain’s existing queue.

Note: If alwaysTryFirst is set to either true or false, then the domains listed in alwaysTryFirstList have no bearing on the behavior specified in alwaysTryFirst.

Related Keys: alwaysTryFirst



Possible Values: a list of domains

Initial Value: null

Default Value: null

Example: /*/mta/alwaysTryFirstList: [software.com]

[hardware.com]



��&��'(��

��&��)��

Description: Character set that auto-reply messages use.

Related Keys: none



Possible Values: us-ascii

Initial Value: us-ascii

Default Value: us-ascii

Example: /*/mta/autoReplyCharset: [us-ascii]

Description: Default auto-reply message.

When mail arrives for an account that has the auto-reply feature enabled, the system automatically generates a text message in response. You can establish the content of on a per account basis (with the imreplyctrl command) and the message is typically different for each account.

If an account has the auto-reply feature enabled, but an account-specific reply message does not exist, the system uses the autoReplyDefaultMessage message.

autoReplyDefaultMessage may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: autoReplyCharset




Initial Value: null

Default Value: no autoreply message defined

Example: /*/mss/autoReplyDefaultMessage: [hello]

Configuration Keys


��&�� !��)��

Description: Number of days until the restriction on vacation auto-reply messages expires.

When an account has the auto-reply feature enabled in Vacation mode, users who send messages to that account receive only one copy of the vacation message within a specified time period.

autoReplyExpireDays sets the number of days before senders are eligible to receive an additional copy of the vacation message. For example, a value of 7 indicates that users can receive another copy of an account’s vacation message every seven days.

A null value indicates no limit.

Related Keys: none



Possible Values: any integer greater than zero

Initial Value: null

Default Value: 7

Example: /*/mss/autoReplyExpireDays: [7]



��&��

Description: List of senders who will not receive automatic responses from InterMail’s auto-reply feature. This key indicates addresses to which sending an auto-reply would typically be inappropriate (for example, mailing list managers or other auto-reply addresses).

The system interprets entries in autoReplySuppressList as the local portion of a standard e-mail address. The key applies to all addresses whose local portion matches an entry in the list.

For example, if listserv is in the list (which it is by default), then the MTA will never send an auto-reply message to any address with listserv as its local portion (such as [email protected], [email protected], or [email protected]).

autoReplySuppressList may include multiple entries, but each entry must appear on a separate line between its own set of square brackets.

Related Keys: none



Possible Values: any RFC821-compliant username (the local portion of an e-mail address)

Initial Value: the entries autoanswer, echo, list.manager, listproc, listserv, mailer, mailerdaemon, mailer-daemon,

majordomo, mirror, netserv, server, and uucp

Default Value: null

Example: /*/mta/autoReplySuppressList:

[listserv]

[echo]

[list.manager]

Configuration Keys


��*��

��)��

Description: Specifies whether the MSS or Directory server will be allowed to conduct online backups.

Related Keys: none

Servers Affected: MSS, Directory server

Change Impact: Trivial

Possible Values: true, false



Example: /*/mss/backupMode: [false]

Description: Amount of time (in seconds) that a bad password will delay subsequent authentication attempts during the same connection. Delays are cumulative up to the limit maxBadPasswordDelay defines.

You can use this key independently on either the POP server or the IMAP server. When the server variable is common, it affects both servers.

Note: A value of 0 (zero) means there will be no delay between re-authentication attempts when the user submits a bad password.

Related Keys: maxBadPasswordDelay

Servers Affected: POP server, IMAP server


Possible Values: any non-negative integer (including zero)

Initial Value: 5

Default Value: 5

Example: /*/common/badPasswordDelay: [5]



��+��

��)��

Description: Limit on the amount of time (in minutes) that the system tracks information about bad password attempts on a particular account or from a particular IP address (calculating the password delay time uses both).

After this period has elapsed, InterMail resets the number of failed password attempts to zero, thereby removing any restrictions previously imposed by InterMail’s password defense mechanisms on a particular account or IP address.

You can use this key independently on either the POP server or the IMAP server. When the server variable is common, it affects both servers.

Related Keys: none




Initial Value: 120

Default Value: 120

Example: /*/common/badPasswordWindow: [120]

Description: Directory where InterMail binaries are installed on this logical host.

Related Keys: none.

Servers Affected: All servers potentially affected.

Change Impact: Server restart required

Possible Values: A valid absolute path name.

Initial Value: $INTERMAIL/bin

Default Value: null

Example: /*/common/binDir: [/imail/imail/bin]

Configuration Keys


��*,��

Description: Enables/disables mail blocking by e-mail address.

When true, the MTA checks the MAIL FROM: address of each incoming message against the addresses in the blockTheseAddresses list. If there is a match, the server rejects the message and logs the rejection.

When false, the MTA does not block mail based on the sender’s address (regardless of entries in blockTheseAddresses).

Note: The blockPerAccount configuration key further restricts the application of blocking policies.

Related Keys: blockTheseAddresses, blockPerAccount






Example: /*/mta/blockAddresses: [false]



��*'��

Description: Enables/disables mail blocking by client IP address.

When true, the MTA checks the client’s IP address against the list of IP addresses in blockTheseIPs. If there is a match, the system blocks all messages sent by that client and a log entry records this event.

When false, the MTA does not block mail based on the connecting IP address (regardless of entries in blockTheseIPs).


Related Keys: blockTheseIPs, blockPerAccount






Example: /*/mta/blockConnections: [false]

Configuration Keys


��*)��

Description: Enables/disables mail blocking by sender domain.

When true, the MTA checks the domain portion of the MAIL FROM: address against the addresses in the blockTheseDomains list. If the address includes a listed domain, it blocks the message .

When false, the MTA does not block mail based on the domain in the sender’s address (regardless of blockTheseDomains ).


Related Keys: blockTheseDomains, blockPerAccount






Example: /*/mta/blockDomains: [false]



��*��,��

Description: Enables/disables the verification of local sender addresses.

When true, the system checks the domain portion of the MAIL FROM: address against the list of local mail domains in the Integrated Services Directory (ISD). If this address includes a local mail domain, it asks the Directory server to verify the existence of the sender address in the ISD. If the address does not exist, it blocks the message.

This feature prevents users from fraudulently including one of your domains in their e-mail addresses, which might allow them to avoid mail blocking or other policies.


Related Keys: blockPerAccount






Example: /*/mta/blockLocalNoAcct: [false]

Configuration Keys


��*��,��

��*&��'��

Description: Indicates whether to apply mail blocking policies and any reject instructions listed in the incomingMailFilter configuration key globally or on a per-account basis.

If false, then blocking policies and any reject instructions listed in incomingMailFilter apply universally to all recipients of incoming mail.

If true, then blocking policies and any reject instructions listed in incomingMailFilter only apply to messages whose recipients desire mail blocking (their account profile in the Integrated Services Directory indicates).

Related Keys: none






Example: /*/mta/blockPerAccount: [false]

Description: Three-digit SMTP error code sent to the client when blocking a message. By default, error code is 550, the standard SMTP code to indicate that the client operation was not successful.

The text specified in blockReplyTest accompanies this code.

Related Keys: blockReplyText



Possible Values: any integer from 400 to 599

Initial Value: 550

Default Value: 550

Example: /*/mta/blockReplyCode: [550]



��*&��$�!�

��*$(��,��

Description: Error text to return with the blockReplyCode error code. This text informs the client of the nature of the message failure.

If the text string includes the word ADDRESS, the system treats the string as a variable and replaces it with the recipient’s address.

blockReplyText may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: blockReplyCode




Initial Value: you are not allowed to send mail to ADDRESS

Default Value: you are not allowed to send mail to ADDRESS

Example: /*/mta/blockReplyText:

[We’re sorry, but you may not ]

[send mail to ADDRESS.]

Description: Addresses the MTA blocks if blockAddresses is true.

blockTheseAddresses may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: blockAddresses



Possible Values: any valid e-mail address

Initial Value: null

Default Value: null

Example: /*/mta/blockTheseAddresses:

[[email protected]]

[[email protected]]

Configuration Keys


��*$(��)��

Description: List of domains the MTA blocks if blockDomains is true.

Domain names may be fully qualified (such as, software.com), or they may include a wildcard prefix (such as, *.software.com). Using a wild card blocks all subdomains associated with a given domain (such as sales.software.com or support.software.com).

blockTheseDomains may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: blockDomains



Possible Values: any fully qualified domain name or a domain name that includes a wildcard prefix

Initial Value: null

Default Value: null

Example: /*/mta/blockTheseDomains: [scam.com]

[bogus.com]

[*.bogus.com]



��*$(��

Description: List of IP addresses the MTA blocks if blockConnections is true.

To specify all systems within a class-C network, use a 0 (zero) as a wildcard (for example, 10.3.21.0). You may also enter IP addresses as subnets to specify all systems within a range of IP address (for example, 10.3.21.16/24).

blockTheseIPs may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: blockConnections



Possible Values: any valid IP address

Initial Value: null

Default Value: null

Example: /*/mta/blockTheseIPs:

[10.3.21.0]

[21.5.117.4]

Configuration Keys


��*$(��-��

Description: List of usernames the MTA blocks if blockUsers is true.

This blocks users based only on the local portion of their addresses. For example, if big.bucks were on the list, it would also block mail from [email protected], [email protected], and big.bucks@<anydomain.com>.

blockTheseUsers may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: blockUsers



Possible Values: any valid username (the local portion of an e-mail address)

Initial Value: null

Default Value: null

Example: /*/mta/blockTheseUsers:

[big.bucks]

[hacker]



��*-��

��)��.��

Description: Enables/disables mail blocking by the sender’s username.

When true, the MTA checks the username portion of the MAIL FROM: address of all incoming messages against the usernames listed in blockTheseUsers. If the address includes a listed username, it blocks the message.

When false, the MTA does not block mail based on the sender’s username (regardless of entries in blockTheseUsers ).


Related Keys: blockTheseUsers, blockPerAccount






Example: /*/mta/blockUsers: [false]

Description: Amount of memory (in bytes) to allocate for handling message body parts. If a body part exceeds this size, InterMail will keep the data in a file rather than in memory.

Related Keys: none




Initial Value: 32768

Default Value: 32768

Example: /*/common/bodyDataBuffer: [32768]

Configuration Keys


��.��

Description: Text in the bounce notification sent with any SMTP 5xx error code.

The entry for this key may include macros, enclosed in angle brackets (< >). Real text will replace the macros when sending this message. The following example identifies supported macros.

bounceFailureBody may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: bounceFailureHeader



Possible Values: a text string (which may include any of the supported macros)

Initial Value: as indicated in the example below

Default Value: null

Example: /*/mta/bounceFailureBody:

[Content-Type: text/plain]

[]

[This Message was undeliverable due to the

following ]

[reason:]

[]

[<ErrorText>]

[]

[Please reply to Postmaster@<PostmasterDomain>]

[if you feel this message to be in error.]



��"��

Description: Header text in the bounce notification sent with any SMTP 5xx error code.

The entry for this key may include macros, enclosed in angle brackets (< >). Real text replaces the macros when sending this message. The following example identifies supported macros.

bounceFailureHeader may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: bounceFailureBody



Possible Values: a header (which may include any of the supported macros)


Default Value: null

Example: /*/mta/bounceFailureHeader:

[To: <ReturnAddress>]

[From: Mail Administrator <Postmaster@<Domain>>]

[Reply-To: Mail Administrator

<Postmaster@<Domain>>]

[Subject: Mail System Error – Returned Mail]

Configuration Keys


��/�#��

Description: Response to incoming messages that would cause a recipient’s mailbox to exceed one of its defined quotas.

If true, the MTA returns the message to its sender.

If false, it queues the message for internal delivery, reattempting delivery at regular intervals that deferProcessInterval defines.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/bounceOnQuotaFull: [true]



��#��

Description: Message to put in a mailbox every time it bounces a message because that mailbox is over quota. The maximum number of unread bounce notices allowed in any mailbox is maxBounceNotices.

Note: If maxBounceNotices is 1 or greater, you should define a message in this configuration key.

The entry for this key may include macros, enclosed in angle brackets (<>). Real text replaces the macros before sending the message. The following list identifies supported macros.

• <Available_Resource>

indicates the unused portion of a user’s quota

• <Requested_Resource>

indicates the quota exceeded (including maximum mailbox size, maximum message size, and maximum number of mes-sages in a mailbox)

• <User_Quota>

indicates the user’s total quota

• <Bounced_Message_From>

indicates the content of the bounced message’s From: header

• <Bounced_Message_Reply_To>

indicates the content of the bounced message’s Reply To: header

• <Bounced_Message_ID>

indicates the message ID of the bounced message

• <Bounced_Message_Date>

indicates the date of the bounced message

• <Bounced_Message_Subject>

indicates the content of the bounced message’s Subject: header

• <Bounced_Message_Size>

indicates the size of the bounced message

Related Keys: maxBounceNotices





Default Value: null

Configuration Keys


Example: /*/mss/bounceQuotaNotice:

[Return-Path: <>]

[From: <Bounce_Notice_From>]

[Subject: <Bounce_Notice_Subject>]

[Date: <Bounce_Notice_Date>]

[]

[A message was sent to you that was returned to ]

[the sender(bounced) because it would have caused

]

[your mailbox quota to be exceeded.]

[]

[The following is the reason that the message was ]

[over quota:]

[]

[Quota Type: <Requested_Resource>]

[Quota Available: <Available_Resource>]

[Total Quota: <User_Quota>]

[]

[The following is the information on the message ]

[that was bounced:]

[]

[Sender: <Bounced_Message_From>]

[Subject: <Bounced_Message_Subject>]

[Size: <Bounced_Message_Size>]

[Message ID: <Bounced_Message_ID>]

[Date: <Bounced_Message_Date>]

[Reply_To: <Bounced_Message_Reply_To>]

[]

[To fix this problem, delete some messages from ]

[your mailbox, and contact the sender to resend ]

[the message.]

[]

[If the size of the message is too big, contact ]

[the sender to reduce the size of the message and ]

[resend the message.]



��.��

Description: Text in the bounce notification sent to indicate bouncing of a successful delivery status notification (DSN).


bounceSuccessBody may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: bounceSuccessHeader





Default Value: null

Example: /*/mta/bounceSuccessBody:

[Content-Type: text/plain]

[]

[<ErrorText>]

[]

[Please reply to Postmaster@<PostmasterDomain>]

[if you feel this message to be in error.]

Configuration Keys


��"��

��*��'��

Description: Header text in the bounce notification sent to indicate bouncing of a successful delivery status notification (DSN).


bounceSuccessHeader may include multiple lines of text, but each line must be within its own set of square brackets.

Related Keys: bounceSuccessBody



Possible Values: a header (which may include any of the supported macros)


Default Value: null

Example: /*/mta/bounceSuccessHeader:

[To: <ReturnAddress>]

[From: Mail Administrator Postmaster@<Domain>>]

[Reply-To: Mail Administrator

<Postmaster@<Domain>>]

[Subject: Mail System Delivery Report]

Description: Number of bucket directories to create within the Control and Messages directories.

You should not modify this value once service has begun, as messages that are already in the system could end up in the wrong bucket.

Related Keys: none




Initial Value: 499

Default Value: 499

Example: /*/mta/bucketCount: [499]



��(��.

��0�

Description: Maximum size (in kilobytes) of the server’s cache.

Related Keys: none




Initial Value: 256

Default Value: 256

Example: /*/common/cacheLimitInKB: [256]

Description: Indicates whether to complete of the MAIL FROM: address on incoming messages.

When true and the MAIL FROM: address on an incoming message is incomplete, it completes the address with the domain name in the defaultDomain configuration key.

If false and the MAIL FROM: address on an incoming message is incomplete, it bounces the message.

Related Keys: defaultDomain




Initial Value: true

Default Value: true

Example: /*/mta/canonicalize: [true]

Configuration Keys


�(��*,��(��

�(��*��

Description: Indicates whether to validate From: and MAIL FROM: address lines against the addresses in the Integrated Services Directory.

If true, authenticated SMTP login (using the AUTH LOGIN command) is necessary for addresses with Authenticated SMTP enabled in their account profile. If false, SMTP authentication is not necessary for any address.

Also, the checkAuthentication key affects whether mail can be sent from a non-existent user in the MAIL FROM:. If checkAuthentication is false, you can send mail from a non-existent user. If it is true, you cannot.

Related Keys: none






Example: /*/mta/checkAuthentication: [false]

Description: The number of seconds to wait between checkpointing database files.

Related Keys: none

Servers Affected: MSS and Directory server

Change Impact: trivial

Possible Values: 1 - 3600 seconds

Initial Value: 1

Default Value: 1

Example: /*/common/checkPointInterval: [1]



�(��*��&��

Description: The number of seconds to wait before retrying a checkpoint that fails, for example, when txn_checkpoint returns DB_INCOMPLETE)

Related Keys: none

Servers Affected: MSS and Directory server


Possible Values: 1 - 3600 seconds

Initial Value: 1

Default Value: 1

Example: /*/common/checkPointRetryInterval: [1]

Configuration Keys


��'��$��

Description: Limits for the number of simultaneous SMTP connections. You may establish limits for an individual IP address or for a range of IP addresses. In addition, you may establish a default limit for IP addresses other than those specifically listed.

If the number of connections exceeds the configured value, it drops the SMTP connection with a 421 error. While this does not definitively stop junk e-mail, it does reduce the ability of junk e-mailers from appropriating all available resources for such undesirable transmissions.

Every entry in the list should be on a separate line, between its own set of square brackets. The content within the brackets should be in the form indicated below (with no spaces):

<ip_address>[/<significant_bits>]:<num_connections>

The entry that follows specifies that for IP address 207.42.31.10, only 10 simultaneous connections should be allowed at any time:

207.42.31.10:10

The entry that follows specifies that the IP address 209.33.47.110 or any address whose first 8 bits match this IP number, will be allowed an unlimited number of simultaneous connections:

209.33.47.110/8:unlimited

The entry that follows specifies that for any unspecified IP address, the maximum number of simultaneous connections will be 5:

default:5

Related Keys: none



Possible Values: zero or more entries in the format: <ip_address>[/<significant_bits>]:<num_connections>

Initial Value: null (allows an unlimited number of simultaneous connections)

Default Value: null (allows an unlimited number of simultaneous connections)

Example: /*/mta/clientConnectionLimitTable:

[198.116.0.0/16:2]

[198.146.0.0/16:2]

[198.147.0.0/16:2]

[10.0.0.0/8:2]

[default:unlimited]



��"��

Description: Number of thread heaps the various InterMail servers use. You may set this key for each server individually, or for all servers as a group.

clientHeaps can increase performance by reducing thread contention for heap access.

Note: You may enter a value larger than the number of threads for a particular server; it simply does not use the additional heaps.

Related Keys: none




Initial Value: Directory server: 16MTA: 64MSS: 16POP server: 32IMAP server: 32remaining servers: 16

Default Value: 32

Example: /*/mta/clientHeaps: [64]

Configuration Keys


��(��

Description: Maximum line length before rejecting an SMTP client’s command or data line.

If zero, there is no limit on server response lengths; however, this would allow a hostile client to force the MTA to run out of memory.

Note: The minimum RFC821 command line length is 512, and the RFC821 maximum line length is 1000.

Related Keys: none




Initial Value: 1000

Default Value: 1000

Example: /*/mta/clientLineLengthLimit: [1000]



��$��

��1��

Description: Maximum amount of time (in seconds) a client may stay connected without issuing any commands. After this period has elapsed, the POP server or IMAP server may end the session without waiting for the client’s request.

RFC 2060 mandates that this period must be no less than 1800 seconds (30 minutes). The default is according to the RFC; however, you are free to modify this value. A value of zero disables the timeout entirely.

Related Keys: none

Servers Affected: POP server, IMAP server, Directory server



Initial Value: POP server: 240 (4 minutes)IMAP server: 1800 (30 minutes)

Default Value: POP server: 240 (4 minutes)IMAP server: 1800 (30 minutes)

Example: /*/popserv/clientTimeout: [240]/*/imdirserv/clientTimeout: [240]/*/imapserv/clientTimeout: [1800]

Description: UNIX group ID (GID) under which InterMail server processes will run.

It is critical that this group name be the one used during InterMail installation: if not, InterMail directory and file name permissions will be incorrect.

Related Keys: commonUser



Possible Values: a valid GID on the machine on which InterMail is installed

Initial Value: the InterMail GID provided during installation

Default Value: imail

Example: /*/common/commonGroup: [imail]

Configuration Keys


��-��

��(��

Description: UNIX user ID (UID) under which all InterMail server processes will run.

It is critical that this user name be the one used during InterMail installation, and it must be part of the commonGroup group, or InterMail directory and file name permissions will be incorrect.

Related Keys: commonGroup



Possible Values: a valid UID on the machine on which InterMail is installed

Initial Value: the InterMail UID provided during installation

Default Value: imail

Example: /*/common/commonUser: [imail]

Description: Determines the MTA’s response to an incomplete RCPT TO: or header address on an incoming message.

If default, it will complete the address with the value in the defaultDomain configuration key.

If bounce, it will not attempt to complete the address, but will bounce the message.

If sender, it will complete addresses for local senders only (using the domain in the sender’s MAIL FROM: address).

The system considers a message to be from a local sender if the domain in the MAIL FROM: address matches one of the known mail domains listed in the Integrated Services Directory (any local, nonauthoritative, or rewrite domain).




Possible Values: default, bounce, or sender

Initial Value: default

Default Value: default

Example: /*/mta/completionMethod: [default]



��

��&��0�

Description: The location of the configuration file for LDAP functions in the Integrated Services Directory.

Related Keys: none

Servers Affected: Directory server


Possible Values: A file location relative to $INTERMAIL

Initial Value: null

Default Value: null

Example: /*/imdirserv/configFiles:

[config/slapd.at.conf]

[config/slapd.oc.conf]

Description: Adjusts (only upward) the size of the recorder buffer used for recording the current configuration values being used by InterMail. Since this buffer is not written to any file, it will grow as needed to accommodate the key/value pairs.

Related Keys: None.

Servers Affected: All servers.

Change Impact:

Possible Values: any non-negative integer (zero disables the recorder buffer).



Example: /*/common/configRecorderSize: [10240]

Configuration Keys


��"��

��

Description: Host on which the Configuration server is running. All servers need to know the location of the Configuration server so that they can retrieve updated configuration information.

Related Keys: none



Possible Values: any valid host name


Default Value: null

Example: */common/confServHost: [paris]

Description: Port number that the Configuration server listens on for connection requests from other InterMail programs.

Related Keys: none

Servers Affected: the Configuration server




Default Value: 0

Example: /*/imconfserv/confServPort: [5000]



��$��

Description: Time stamp of the last configuration database update.

confTimeStamp goes into a config.db file when writing the file to disk. The system uses it when another server connects to the Configuration server. The system compares confTimeStamp in the local config.db file to confTimeStamp in the master config.db file to quickly determine if the two configuration databases are the same (or if resynchronization is necessary).

Servers do not use this value directly. Do not set this key manually, as the Configuration server will reset it.

Related Keys: none



Possible Values: any valid date and time in UNIX datetime format (see example below)

Initial Value: null

Default Value: null

Example: /*/common/confTimeStamp: [Wed May 6 17:49:38 EDT 1998]

Configuration Keys


��)��

��-��

Description: Indicates whether InterMail will attempt to convert IP addresses to literal domain names.

If true, then the system will deliver mail sent to an e-mail address that includes an IP address (for example, [email protected].) if the IP address actually maps to a valid destination domain (for example, software.com).

If false, mail for literal IP addresses will bounce with a host not found error.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/convertDomainLiterals: [true]

Description: Amount of time (in seconds) that the MSS will cache class-of -service information before refreshing it from the Integrated Services Directory.

Related Keys: none



Possible Values: any integer

Initial Value: 300 (5 minutes)

Default Value: 300 (5 minutes)

Example: /*/mss/cosMinUpdateSeconds: [300]



��!��

��!��0��

Description: Enables/disables the creation of mailboxes “on the fly.”

When true, the system creates a mailbox automatically the first time it is necessary. (It is necessary the first time a message arrives for the account, or the first time the user attempts to retrieve mail).

Setting this key to true allows you to create accounts in the Integrated Services Directory without explicitly creating mailboxes for the new accounts in an MSS database: InterMail will create the mailbox when necessary.

When false, you must explicitly create a mailbox for every new account.

You can specify this key independently for MTA, IMAP, POP, and Web servers, which allows you to limit mailbox creation to time of message delivery (by setting MTA only) or message retrieval (by setting IMAP, POP, and/or Web).

Related Keys: none

Servers Affected: MTA, POP server, IMAP server



Initial Value: true

Default Value: true

Example: /*/common/createsMboxes: [true]

Description: The maximum size of a database log file. Database log files are used for recovery from crashes.

Related Keys: none



Possible Values: any non-negative integer

Initial Value: 64

Default Value: 64

Example: /*/mss/dbLogFileMaxSizeKb: [64]

Configuration Keys


��!'��(��0��.

��!��0��.

Description: The size of the in-memory cache for the mbox database.

Related Keys: none




Initial Value: 16

Default Value: 16

Example: /*/mss/dbMboxCacheSizeinKB: [16]

Description: The page size for the mbox file for the database.

Related Keys: none




Initial Value: 16

Default Value: 16

Example: /*/mss/dbMboxPageSizeinKB: [16]



��'��(��0��.

��0��.

Description: The size of the in-memory cache for the msgid database.

Related Keys: none






Example: /*/mss/dbMsgIdCacheSizeinKB: [16384]

Description: The page size for the msgid database.

Related Keys: none




Initial Value: 16

Default Value: 16

Example: /*/mss/dbMsgIdPageSizeinKB: [16]

Configuration Keys


��0��.

��!

��%��

Description: Page size (in kilobytes) to use for reading from and writing to the Integrated Services Directory. If 0, the page size depends on the underlying file system’s I/O block size.

Related Keys: none



Possible Values: 0-64

Initial Value: 16

Default Value: 16

Example: /*/imdirserv/dbPageSizeInKB [16]

Description: The DN (Distinguished Name) suffixes handled by the Integrated Services Directory.

Related Keys: none



Possible Values:

Initial Value: null

Default Value: null

Example: /*/imdirserv/dbSuffix: [ ]

Description: Cause the database to output more verbose logging information.

Related Keys:





��,��




Example: /*/mss/dbVerboseFlag: [false]

Description: Name of the sender to use in messages the MSS generates.

The MSS is responsible for creating over-quota bounce messages, and near-quota notifications.

Related Keys: none



Possible Values: any text string

Initial Value: admin

Default Value: admin

Example: /*/mss/defaultAdminName: [admin]

Configuration Keys


��)��

��*��0��.

Description: Default domain name the MTA uses to complete unqualified addresses for message recipients or senders, or to complete unqualified host names in a message route, if completionMethod is default.

Note: If defaultDomain is null, then the MTA uses domainName for address completion (when required).

Related Keys: completionMethod



Possible Values: any valid domain name

Initial Value: null

Default Value: null

Example: /*/mta/defaultDomain: [software.com]

Description: Default stack size (in kilobytes) for new threads created in servers. If null or zero, uses the operating system default.

The system can only set the stack size for a thread at its creation.

Related Keys: none




Initial Value: 64

Default Value: 0

Example: /*/common/defaultStackSizeInKB: [64]



��/��!��*��

��

Description: Indicates whether, on failing to locate an MX record, the system immediately defers the message or attempts to locate an A record.

When true and an MX record lookup times out or the server cannot otherwise process the query, it defers the mail.

When false and an MX record lookup times out, the MTA then initiates an A record lookup. If the A record lookup also fails, it defers the mail.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/deferOnMxLookupFail: [true]

Description: Interval (in seconds) at which the system will re-attempt delivery of mail deferred for an internal server (that is, mail that the system could not deliver immediately because a mailbox or user account information was temporarily unavailable).

Related Keys: none






Example: /*/mta/deferProcessInterval: [600]

Configuration Keys


��&��'��

��&��"��

Description: Maximum number of client connections to the Integrated Services Directory. The HTTPD, MTA, MSS, POP server and IMAP server are all potential clients of the Integrated Services Directory. This key defines a connection pool from which these clients can draw on demand.

The system opens connections only when they are actually necessary. Once a connection is open, it stays open unless there is an error.

If all the allotted connections are in use, the Directory server asks clients to wait until another connection becomes free.

Related Keys: none

Servers Affected: all servers that are clients of the Integrated Services Directory


Possible Values: any integer greater than 1

Initial Value: 40

Default Value: 10

Example: /*/common/dirRmeConnections: [40]

Description: Defines a list of hosts running directory caches. First in list is the primary host (usually localhost), others will be used as backups.

Related Keys:

Servers Affected: Directory server.


Possible Values: A colon-separated list of hosts.

Initial Value: null

Default Value: null

Example: /*/common/dirRmeHost: [paris]



��&��!��'��

��&��

��

Description: Warning! This key should only be modified with vendor and/or technical support.

Related Keys: none

Servers Affected: all servers that are clients of the Integrated Services Directory



Initial Value: 100

Default Value: 100

Example: /*/imdirserv/dirRmeMaxSecondaryCalls: [100]

Description: Port number on which the Directory server listens for requests.

Related Keys: none





Default Value: null

Example: /*/imdirserv/dirRmePort: [5888]

Description: Establishes a connection between the Mx IMAP server and the Kx Directory server.

WARNING! Do not modify this key.

Related Keys: none

Servers Affected: IMAP server


Configuration Keys


��

��-��

Possible Values: text string which is either imdircacheserv or imdirserv

Initial Value: imdircacheserv

Default Value: imdircacheserv

Example: /*/common/dirServName [imdirserv]

Description: Domain name to use wherever a domain name is necessary (such as the backup value for address completion, the primary value for host name completion, and so forth).





Initial Value: the domain name provided during installation

Default Value: null

Example: /*/common/domainName: [software.com]

Description: Interval (in seconds) at which the MTA requests updated domain information.

Related Keys: none




Initial Value: 60

Default Value: 60

Example: /*/mta/domainUpdateInterval: [60]



��'��

��!��&'�$�

Description: Enables/disables connection dropping. When true, the system compares the IP address of every connecting client to the list of IP addresses in dropTheseIPs to determine whether to drop the connection. In addition, if dropMaxMessageRCPTs defines a limit on recipients, it counts the message recipients and compares them to that limit. If a connection is in violation of either of these policies, the server immediately terminates the connection.

When false, it disables connection dropping.

Related Keys: dropTheseIPs, dropMaxMessageRCPTs






Example: /*/mta/dropConnections: [false]

Description: Maximum number of recipients allowed before dropping a connection.

If dropConnections is true and a client attempts to send a single message to more than the number of users in dropMaxMessageRCPTs, it drops the connection.

When dropMaxMessageRCPTs is zero, there is no maximum number of recipients specified: the system will allow an unlimited number of recipients per connection.

Related Keys: dropConnections




Initial Value: 0

Default Value: 0

Example: /*/mta/dropMaxMessageRCPTs: [100]

Configuration Keys


��&'�$�&��$�!�

��$(��

Description: Text returned with the 421 error code to clients whose connections the system drops because they exceed the maximum number of recipients per connection that dropMaxMessageRCPTs defines.

Related Keys: dropMaxMessageRCPTs, dropConnections




Initial Value: service unavailable

Default Value: service unavailable

Example: /*/mta/dropRCPTsReplyText: [service unavailable]

Description: List of IP addresses that are subject to connection dropping.

When dropConnections is true, the system compares the IP address of each connecting client to the values in this list. If there is a match, the connection immediately terminates.

dropTheseIPs may include multiple entries, but each entry must appear on a separate line contained within its own set of square brackets.

Zero is a wildcard to specify all hosts within a network (for example, 10.3.21.0).

Related Keys: dropConnections




Initial Value: null

Default Value: null

Example: /*/mta/dropTheseIPs: [100.28.56.44][10.3.21.0]



��)��

��'��(��!'��

Description: Indicates whether to detect duplicate messages. A setting of true enables duplicate detection. The system checks to see if an incoming message is the same as one already stored. If so, it creates a link to the original message and does not store the duplicate.

A setting of false disables duplicate detection.

Note: The process of duplicate detection can be time-consuming. However, this feature may be useful if your mail system receives a large number of duplicate messages.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mss/dupMessageDetect: [true]

Description: Maximum number of entries to keep in the cache for the LDAP Entries database.

Related Keys:



Possible Values: Any non-negative integer.

Initial Value: 1000

Default Value: 1000

Example: /*/imdirserv/entryCacheMaxCount: [1000]

Configuration Keys


��'��(��!��0��.

��2,��3��

Description: Maximum size of the cache for the LDAP Entries database.

Related Keys:



Possible Values: Any non-negative integer (including 0)

Initial Value: 0

Default Value: 0

Example: /*/imdirserv/entryCacheMaxSizeKB: [0]

Description: Error action the MTA takes when a message arrives for a user with a disabled account (through deletion or suspension).

The possible error actions (which you may use independently or in combination) are as follows:

• return: Return the message to its sender

• hold: Hold the message for postmaster action

• log: Record the event in the mta.log

This key supports multiple values; however, each entry must appear on a separate line within its own set of square brackets. The recommended settings are log and return. A null setting means to defer the message.

Related Keys: the corresponding Error-Code and Error-Text configuration keys



Possible Values: one or more of the values return, hold, and log

Initial Value: log and return

Default Value: null

Example: /*/mta/Error-Actions/acctInactive: [log][return]



��2,��3��-��

Description: Error action the MTA takes when a message arrives for an unrecognized destination address (for example, an incomplete address or unknown user).











Default Value: null

Example: /*/mta/Error-Actions/acctInvalidUser: [log][return]

Configuration Keys


��2,��3��&��

Description: Error action the MTA takes when it cannot successfully return an undeliverable message due to a problem with the return address.


return: Return the message to its sender

hold: Hold the message for postmaster action

log: Record the event in the mta.log

This key supports multiple values; however, each entry must appear on a separate line within its own set of square brackets. The recommended settings are log and hold. A null setting means to defer the message.

Related Keys: the corresponding Error-Code configuration key




Initial Value: log and hold

Default Value: null

Example: /*/mta/Error-Actions/badReturn: [log][hold]



��2,��3��,��.��

Description: Error action the MTA takes when a filter for incoming mail determines that it should not deliver a message.


return: Return the message to its sender

hold: Hold the message for postmaster action

log: Record the event in the mta.log







Default Value: null

Example: /*/mta/Error-Actions/filtActionBounce: [log][return]

Configuration Keys


��2,��3��0�

Description: Error action the MTA takes when a message arrives that exceeds the limit on maximum size for a single message (as the associated account profile of the mailbox defines).











Default Value: null

Example: /*/mta/Error-Actions/msLimitMsgSize: [log][return]



��2,��3��

Description: Error action the MTA takes when a message arrives that would exceed the limit on a mailbox’s maximum number of messages (as the associated account profile defines).











Default Value: null

Example: /*/mta/Error-Actions/msLimitNumMsgs: [log][return]

Configuration Keys


��2,��3��$��0�

Description: Error action the MTA takes when a message arrives that would exceed the limit on the maximum size of a mailbox (as the associated account profile defines).











Default Value: null

Example: /*/mta/Error-Actions/msLimitTotalSize: [log][return]



��2,��3��,��)��

Description: Error action the MTA takes when a message arrives for a disabled mailbox.











Default Value: null

Example: /*/mta/Error-Actions/msNoAllowDeliver: [log][return]

Configuration Keys


��2,��3��"��

Description: Error action the MTA takes when a message arrives addressed to an invalid host (a destination machine the system cannot find).











Default Value: null

Example: /*/mta/Error-Actions/mtaHostInvalid: [log][return]



��2,��3��!��"��'�� !��

Description: Action the MTA takes when a message exceeds the maximum number of MTA hops.

A message “hops” when it moves from one MTA to another. The number of Received: lines in a message is the number of hops.





This key supports multiple values; however, each entry must appear on a separate line within its own set of square brackets. The recommended setting is log and hold. A null setting means to defer the message.

Related Keys: maximumMtaHops, the corresponding Error-Code configuration key





Default Value: null

Example: /*/mta/Error-Actions/mtaMaxMtaHopCountExceeded: [log][hold]

Configuration Keys


��2,��3��)��

Description: Determines how to handle a "successful delivery" status notification.


• return: Send the delivery status notification

• hold: Hold the delivery status notification


This key supports multiple values; however, each entry must appear on a separate line within its own set of square brackets. The recommended setting is return. A null setting means to defer the message.

Note: This event is not actually an 'error'—delivery status notifications are similar to bounce messages, and are controlled by configuration keys.





Initial Value: return

Default Value: null

Example: /*/mta/Error-Actions/mtaMessageDelivered: [return]



��2,��3�� !��

Description: Determines how to handle a delivery status notification that indicates a message reached its destination and the system forwarded it to at least two mailboxes or recipients.






Note: This event is not actually an 'error'—delivery status notifications are similar to bounce messages, and are controlled by configuration keys.






Default Value: null

Example: /*/mta/Error-Actions/mtaMessageExpanded: [return]

Configuration Keys


��2,��3��#��$��

Description: Error action the MTA takes when a deferred message has been in the queue longer than the configured limit set in maxQueueTimeInHours.






Related Keys: maxQueueTimeInHours, the corresponding Error-Code and Error-Text configuration keys





Default Value: null

Example: /*/mta/Error-Actions/mtaMessageQueuedTooLong: [log][return]



��2,��3��&�4��

Description: Error action the MTA takes when the receiving SMTP server rejects a message.











Default Value: return

Example: /*/mta/Error-Actions/mtaMessageRejected: [return]

Configuration Keys


��2,��3��&��

Description: How to handle delivery status notification for a message relayed to a machine that does not handle delivery status notification.











Default Value: null

Example: /*/mta/Error-Actions/mtaMessageRelayed: [return]



��2,��3��$��

Description: Error action the MTA takes when it rejects a message because that message is too large (for example, larger than maxMessageSizeInKb).






Related Keys: maxMessageSizeInKb, the corresponding Error-Code and Error-Text configuration keys





Default Value: null

Example: /*/mta/Error-Actions/mtaMessageTooLarge:

[log]

[return]

Configuration Keys


��2,��3��&��

Description: Error action the MTA takes when it receives a message that does not include any recipients.






Related Keys: the corresponding Error-Code configuration key





Default Value: null

Example: /*/mta/Error-Actions/mtaMsgNoRecipients:

[log]

[hold]



��2,��3��&��&�4��

Description: Action the MTA takes when the receiving SMTP server rejects one or more message recipients.











Default Value: null

Example: /*/mta/Error-Actions/mtaRecipientsRejected:

[log]

[return]

Configuration Keys


��2,��3��&�4��

Description: Error action the MTA takes when it cannot deliver a message because the return address is objectionable (for example, if you do not allow that address to send mail to users on your system).






Related Keys: rejectSenderBadDomain, rejectSenderIPDomain, rejectSenderNoDomain, and the corresponding Error-Code and Error-Text configuration keys





Default Value: null

Example: /*/mta/Error-Actions/mtaSenderRejected:

[log]

[return]



��2,��3��'��)��

Description: Error action the MTA takes when it detects a message caught in a mail loop.






Related Keys: maximumMtaHops, the corresponding Error-Code configuration key





Default Value: null

Example: /*/mta/Error-Actions/smtpClientMailLoopDetected: [log][hold]

Configuration Keys


��2,��3��)��.��'��

Description: Error action the MTA takes when it attempts a lookup on an MX record, but fails because the configuration of the DNS records of the remote domain is incorrect.











Default Value: null

Example: /*/mta/Error-Actions/smtpDnsBadConfig:

[log]

[return]



��2,��3��

��2'��3 *��

Description: Error action taken when the system cannot connect to a remote mail server because the remote server does not support the SMTP protocol. The possible error actions (which you may use independently or in combination) are as follows:










Default Value: null

Example: /*/mta/Error-Actions/smtpProtocolNotSupported: [log][return]

Description: Error code returned when the value of the corresponding Error-Action key is return.

Related Keys: the corresponding Error-Action and Error-Text configuration keys


Change Impact: Warning! Do not attempt to modify the value of these keys.

Configuration Keys


��2$�!�3 *��

��!+��

Description: Text of the bounce message returned when the value of the corresponding Error-Action key is return.

Related Keys: the corresponding Error-Action and Error-Code configuration keys


Change Impact: Warning! Do not attempt to modify the value of these keys.

Description: Maximum time (in seconds) a server can wait for any event. After this period expires, servers will time out.

Related Keys: none




Initial Value: 3000

Default Value: 3000

Example: /*/common/eventMaxWait: [3000]



�!��'��'��).��(

Description: Path on the file system to a backup copy of the master configuration database.

If extraCopyConfigDbPath defines a path, the Configuration server writes an extra copy of each new master configuration database file to the location specified.

If extraCopyConfigDbPath is null, the Configuration server does not create a backup copy of the master configuration database.

This configuration key can be an absolute path or a path relative to the InterMail installation directory.

Related Keys: none

Servers Affected: Configuration server


Possible Values: any valid file path

Initial Value: null

Default Value: null

Example: /*/imconfserv/extraCopyConfigDBpath:[cfbak]

Configuration Keys


��"��

Description: Indicates whether all servers attempt to recover from fatal signals.

If true, all servers attempt to recover from fatal signals (SIGILL, SIGABRT, SIGEMT, SIGFPE, SIGBUS, SIGSEGV, and SIGSYS). The system logs the signal and the server attempts to continue.

If false, servers do not attempt to recover when they receive a fatal signal. In this case, you will need to restart the affected server(s) directly.

It is advisable that you set this key to false since, if a server gets a fatal signal, its internal state is most likely corrupt. If the server attempts to proceed in this state, it is possible that the system will lose or misdeliver mail. The server may also hang. For these reasons, it is generally better to restart the server after a fatal signal.

Note: DEC servers ignore this key; DEC servers never attempt to recover from fatal signals.

Related Keys: none






Example: /*/common/fatalSigHandlers: [false]



��)��

��$��

Description: Maximum number of file descriptors that can be open for any server. It is best to keep this number above 100. Each operating system has a specific ceiling. A value of zero specifies the operating system default.

Related Keys: none




Initial Value: MTA: 2048MSS: 2048POP server: 2048IMAP server: 2048remaining servers: 0

Default Value: 0

Example: /*/mta/fileDescriptors: [2048]

Description: Indicates whether to use GMT (Greenwich Mean Time) in log time stamps.

If true, log time stamps use GMT.

If false, log time stamps use local time.

Related Keys: none






Example: /*/common/gmtLogTimes: [false]

Configuration Keys


(��,��

Description: Describes other domain names or IP addresses (for the MTA) that appear in the MX records. Below is an example of what the MX records may look like if the domain name is foo.com:

foo.com. MX 5 foo.comfoo.com. MX 10 <MTA of ISP>

If foo.com is unavailable, the mail is delivered and stored with the ISP. However, an ISP may have different names for the MTAs (internal and external). For example, the external name is mta.isp.com, and the internal name is logos.isp.com. When the ISP tries to send mail to foo.com, and foo.com is not available, it will try to send to mta.isp.com, the secondary location. Since the MTA does not recognize that name (mta.isp.com) as itself, a mail loop is created. The /*/mta/hostnameAliasList key is used in these situations, defining a name that the MTA should look for in the MX records if the actual domain name or IP does not exist.

All records at this MX preference or higher will be removed when sending mail.

Related Keys:



Possible Values: Hostnames, IP addresses, or a mixture of the two.

Initial Value: null

Default Value: null

Example: /*/mta/hostnameAliasList:

[mta.isp.com]

[10.2.6.98]



��($��

��

Description: Minimum number of seconds that a mailbox should remain in the memory of the MSS after activity for the mailbox has ceased.

Related Keys: none




Initial Value: 10

Default Value: 10

Example: /*/mss/idleFlushTimeoutSecs: [10]

Description: The InterManager login name. This name is specified at time of installation.

Related Keys: imanOrg, imanPass, imanUID


Change Impact: Do not change this value in config.db. A serious error may occur.

Possible Values: Any alphanumeric string assigned as a password.

Initial Value: null

Default Value: null

Example: /*/install/imanLogin: [admin]

Configuration Keys


��/��

��

Description: The name of the initial (site) organization.

Related Keys: imanLogin, imanPass, imanUID



Possible Values: Any alphanumeric string assigned as the initial site organization.

Initial Value: null

Default Value: null

Example: /*/install/imanOrg: [CompanyABC]

Description: The password for the InterManager Site Administrator.

Related Keys: imanLogin, imanOrg, imanUID



Possible Values: Any alphanumeric string assigned as the Site Administrator’s password.

Initial Value: null

Default Value: null

Example: /*/install/imanPass: [admin]



��-�)

��5��

Description: The e-mail address for the InterManager Site Administrator.

Related Keys: imanLogin, imanOrg, imanPass



Possible Values: The value of imanLogin and the DefaultDomain, set at time of install.

Initial Value: null

Default Value: null

Example: /*/install/imanUID: [[email protected]]

Description: Port on which the IMAP server listens for incoming connections. The standard IMAP port is 143.

Related Keys: none




Initial Value: 143

Default Value: -1

Example: /*/imapserv/imap4Port: [143]

Configuration Keys


��!��$(��

��!��$(��

Description: Maximum number of threads that the imboxcopy administrative command uses (unless the command’s -threads option overrides).

Related Keys: none

Servers Affected: MSS server



Initial Value: 30

Default Value: 30

Example: /*/mss/imboxcopyNumThreads: [30]

Description: Maximum number of threads the imboxmigrate administrative command can use (unless the command’s -threads option overrides).

Related Keys: none




Initial Value: 30

Default Value: 30

Example: /*/mss/imboxmigrateNumThreads: [30]



��

Description: Set of filtering rules for all incoming mail. A null setting means that the system does not enforce filtering.

InterMail allows you to extend its relay prevention, mail blocking, and message sidelining features with custom mail filters.

Each MTA can have one associated incomingMailFilter key, which defines all of the filtering criteria that that MTA uses.

Because the InterMail filtering feature is extremely flexible, the filtering rules are necessarily complex. Before attempting to set incomingMailFilter, please refer to Chapter 8 of the InterMail Kx Operations Guide for a complete discussion of mail filtering.

InterMail mail filtering uses the SIEVE filtering language. The general syntax of a mail filter is:

if <test> <action> [else <action>];

where:

<test>specifies a Boolean expression that is true or false, based on a characteristic of the message

<action>defines an action the MTA takes on the message.

For example, if the incomingMailFilter key were as follows, it would bounce any incoming message that includes a recipient address in the domain accordance.com.

if RECIPIENTS matches "*@accordance.com" BOUNCE;

The value of the incomingMailFilter key may include multiple lines, but each line must be within its own set of square brackets (see example below).

Note: Since the system does not perform validation checks on this key, it is important that you verify your filters before using them. The administrative command imfiltercheck provides this verification.

Related Keys: blockPerAccount



Possible Values: See Chapter 8 of the InterMail Kx Operations Guide.

Initial Value: null

Default Value: null

Example: /*/mta/incomingMailFilter: [if size >= 100k {][if SENDER.DOMAIN IS-NOCASE ("software.com") KEEP;][else if HEADER("Is-Junk:") IS-NOCASE "yes" TOSS;][else if RECIPIENTS.COUNT >= 100 TOSS;][else SIDELINE "too large";][}]

Configuration Keys


��)��)��

Description: Limit (in kilobytes) for mail in delivery. Mail in delivery includes all messages that the system has not yet delivered or explicitly deferred.

inDeliveryDeferKb allows you to throttle message processing in the event that your system is under load. When mail in delivery exceeds inDeliveryDeferKb, the system automatically defers all incoming mail, and writes an MtaTooBusyDefer entry in the log file.

The system treats mail deferred through throttling just as any other deferred mail, and reprocesses it automatically at regular intervals.

When inDeliveryDeferKb is set to 0, the key is completely disabled.

Related Keys: none






Example: /*/mta/inDeliveryDeferKb: [1000000]



��)��&�4��

Description: Limit (in kilobytes) for mail in delivery. Mail in delivery includes all messages that the system has not yet delivered or explicitly deferred.

inDeliveryRejectKb allows you to throttle message processing in the event that your system is under load. When mail in delivery exceeds inDeliveryRejectKb, the system rejects all incoming mail with a message indicating that it cannot process the mail at this time. In addition, it writes an MtaTooBusyReject entry in the log file. A value of zero means there is no limit.

When inDeliveryRejectKb is not zero, it should always be higher than inDeliveryDeferKb.

By setting inDeliveryDeferKb lower than inDeliveryRejectKb, you reserve the more drastic measure (rejection) for last. The inDeliverDeferKb limit, which it reaches first, merely defers mail, rather than rejecting it outright.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/inDeliveryRejectKb: [0]

Configuration Keys


��)��)��

Description: Limit (in kilobytes) for deferred mail processing based on the current amount of mail in delivery.

The system checks inDeliveryStopDeferProcessKb at the start of each defer processing interval. If the current amount of mail in delivery exceeds inDeliveryStopDeferProcessKb , the system does not process deferred mail and writes an MtaTooBusyStopDefer entry to the log. The system will again attempt to deliver deferred mail at the next defer processing interval.

A value of zero means there is no limit.

Note: Typically, the value of inDeliveryStopDeferProcessKb should be higher than that of inDeliveryDeferProcessKb; this allows mail that is currently in the system to be processed before new incoming mail is processed.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/inDeliveryStopDeferProcessKb: [10000]



��

��'��$��

Description: A list of the LDAP attributes to be indexed for the LDAP component of the Integrated Services Directory. This list shows the indexed attributes and how they are to be indexed.

Related Keys: none



Possible Values: any LDAP attribute(s) and an index action (or actions)

Initial Value: [smtpaddress eq][uid eq,reverse][domainname eq,reverse][userlogin eq][mailid eq][mp eq][mailpolicy eq]

Default Value: See Initial Value.

Example: /*/imdirserv/indices:

[smtpaddress eq]

[uid eq,reverse]

[domainname eq,reverse]

[userlogin eq]

[mailid eq]

[mp eq]

[mailpolicy eq]

Description: POP client timeout (in seconds) during the initialization. If zero, the system uses the default client timeout.

Related Keys: none




Initial Value: 240

Default Value: 0

Example: /*/popserv/initClientTimeout: [240]

Configuration Keys


��)��

��%��

Description: Directory where InterMail is installed on this logical host.

Related Keys: none.

Servers Affected: All Servers potentially affected.



Initial Value: The install directory specified at installation time.

Default Value: null

Example: /*/common/installDir: [/imail/imail]

Description: Indicates the version of InterMail installed.

Related Keys: none

Servers Affected: all


Possible Values: Same as the version number reported from, for example:

$INTERMAIL/lib/mss -version

Initial Value: the installed InterMail version

Default Value: no entry value

Example: /*/common/InterMailVersion:[K.4.02.00 201-232-114]



��,��

��'��$��

Description: A list of hosts that have access to the LDAP server.

Related Keys:



Possible Values: A hostname or colon-separated list of hosts.

Initial Value: null

Default Value: null

Example: /*/imdirserv/ldapAccessList: []

Description: The idle client connection timeout value.

Related Keys:



Possible Values: 0 to 86400

Initial Value: 0

Default Value: 0

Example: /*/imdirserv/ldapClientTimeout: [0]

Configuration Keys


��'��

��)� ��'��(��0��.

Description: List of LDAP configuration files to be read and used by the Directory server.

Related Keys:



Possible Values: A list of LDAP configuration files.

Initial Value: null

Default Value: null

Example: /*/imdirserv/ldapConfigFiles:[config/slapd.at.conf][config/slapd.oc.conf]

Description: Size of the cache to maintain for LDAP Entries database in the Integrated Services Directory.

Related Keys: none



Possible Values: Any non-negative integer (in kb)



Example: /*/imdirserv/ldapDbEntryCacheSizeInKB: [16384]



��)� ��0��.

��)��!'��(��0��.

Description: Page size to maintain for the LDAP Entries database in the Integrated Services Directory.

Related Keys: none




Initial Value: 16

Default Value: 16

Example: /*/imdirserv/ldapDbEntryPageSizeInKB: [16]

Description: Size of the cache to maintain for the LDAP Index database in the Integrated Services Directory.

Related Keys: none



Possible Values: Any non-negative integer (in KB)



Example: /*/imdirserv/ldapDbIndexCacheSizeInKB: [16384]

Configuration Keys


��)��!��0��.

�� '��(��!'��

Description: Page size for the LDAP Index database in the Integrated Services Directory.

Related Keys: none




Initial Value: 16

Default Value: 16

Example: /*/imdirserv/ldapDbIndexPageSizeInKB: [16]

Description: The maximum number of LDAP entries to cache in memory.

Related Keys: ldapEntryCacheMaxSizeKb



Possible Values: Any non-negative integer (including 0).

Initial Value: 1000

Default Value: 1000

Example: /*/imdirserv/ldapEntryCacheMaxCount: [1000]



�� '��(��!��0��

��"��

Description: The maximum amount of LDAP entries to cache in memory, measured in terms of KB of entry data.

Related Keys: ldapEntryCacheMaxCount




Initial Value: 0

Default Value: 0

Example: /*/imdirserv/ldapEntryCacheMaxSizeKb: [0]

Description: Name of the host providing LDAP service.

Related Keys: none



Possible Values: Any valid host name.

Initial Value: null

Default Value: null

Example: /*/common/ldapHost: [paris]

Configuration Keys


��

�� )��

Description: Values defined for LDAP transactions.

Related Keys:


Change Impact: server restart required.

Possible Values:

Initial Value: See Example

Default Value: null

Example: /*/imdirserv/ldapIndices:[smtpaddress eq,reverse][uid eq,reverse][domainname eq,reverse][domaintype eq][userlogin eq][mailid eq][mp eq][mailpolicy eq][rewritename eq][alloweddomains eq][defaultmailuserprofile eq][o eq][ou eq][description eq][businesscategory eq]

Description: Number of files to split the LDAP Entries database into on disk.

Related Keys: ldapNumIndexDbFiles



Possible Values: any integer equal or greater to 1

Initial Value: 8

Default Value: 8

Example: /*/imdirserv/ldapNumEntryDbFiles: [8]



��!)��

��/��

Description: Number of files to split the LDAP Index database into on disk.

Related Keys: ldapNumIndexDbFiles



Possible Values: any integer equal or greater to 1

Initial Value: 8

Default Value: 8

Example: /*/imdirserv/ldapNumIndexDbFiles: [8]

Description: The number of allowable LDAP client operations allowed per connection

Related Keys: none




Initial Value: 10

Default Value: 10

Example: /*/imdirserv/ldapOperationLimit: [10]

Configuration Keys


��&��

��&��&��"��

Description: Location of the LDAP replication log file for the Integrated Services Directory.

Related Keys: none



Possible Values: A file location relative to $INTERMAIL

Initial Value: null

Default Value: null

Example: /*/imdirserv/ldapRepLogFile: []

Description: Sets the interval at which the LDAP replication log is rolled over. (If set to 0, the replication log is never rolled over).

Related Keys: none




Initial Value: 1

Default Value: 1

Example: /*/imdirserv/ldapRepLogRollHours: [1]



��&��)�

��&��

Description: The root Distinguished Name (DN) for the server.

Related Keys: ldapRootPwd



Possible Values: a proper DN specification

Initial Value:

Default Value: [cn=root]

Example: /*/imdirserv/ldapRootDn: [cn=root]

Description: The password for the root entry on the server.

Related Keys: ldapRootDn



Possible Values: a password

Initial Value:

Default Value:

Example: /*/imdirserv/ldapRootPwd: [secret]

Configuration Keys


��(��'(��*

��0��

Description: Determines whether schema checking should be enabled in the LDAP component of the Integrated Services Directory.

Related Keys: none






Example: /*/imdirserv/ldapSchemaCheck: [false]

Description: The size limit on the search operations in the LDAP component of the Integrated Services Directory, in number of entries matched.

Related Keys: ldapTimeLimit




Initial Value: 500

Default Value: 500

Example: /*/imdirserv/ldapSizeLimit: [500]



��$��

��"��

Description: The time limit on the search operations in the LDAP component of the Integrated Services Directory, in seconds.

Related Keys: ldapSizeLimit





Default Value: 3600

Example: /*/imdirserv/ldapTimeLimit: [3600]

Description: List of the hosts from which the Manager server accepts connections. Only the hosts that appear in this list respond to commands from the Manager server (such as stop, start, restart, and drain).

legalHosts may consist of one or more hostnames (not IP addresses) each on a separate line enclosed by square brackets. A value of all specifies all hosts on the system.

The InterMail installation process manages the content of this configuration key. As each new host joins the system, the system includes it in the legalHosts key in the master configuration database.

Related Keys: none

Servers Affected: Manager server



Initial Value: all

Default Value: all

Example: /*/immgrserv/legalHosts:

[paris]

[jupiter]

[paris]

Configuration Keys


��

Description: The license for InterMail limits the number of organizations that can be created in InterManager, and the capabilities you can give to the users you create. The limits set on the mail system are:

Number of Organizations (in InterManager)

Users with POP service

Users with IMAP service

Users with WebEdge service

Users with POP/SSL capability

Users with SMTP/SSL capability

Related Keys: none.



Possible Values: Non-negative integers for each type of access.

Initial Value: /*/common/licenseKey:

[signature: f4186a1a7736db04c82adab060d65068

[orgs: 1]

[prefimap: 5]

[prefpop: 5]

[prefpopssl: 5]

[prefsmtpssl: 5]

[prefwebmail: 5]

Default Value: See Initial Value.

Example: See Initial Value.



��+��$(��(��)��

��.��*��

Description: Indicates the number of days before license expiration warnings are generated. The default is 30 days. For keys that expire in 10 days, change this key to 2.

Related Keys: none

Servers Affected: all servers that use the license


Possible Values: 1 to INT_MAX

Initial Value: 30

Default Value: 30

Example: /*/common/licenseWarnThresholdDays: [30]

Description: Size of the backlog queue of the Listener thread.

The Listener creates a connection queue for all network connections on the port attached to the socket. When another machine tries to connect to the port (such as SMTP or POP), the system holds its connection request in the queue; if the queue is full, then it rejects the connection.

Related Keys: none




Initial Value: 1024

Default Value: 1024

Example: /*/common/listenBacklog: [1024]

Configuration Keys


��*$��

��)��

Description: Number of seconds the POP server waits before releasing its lock on a user’s mailbox. With the lock released, other POP clients can connect to the same mailbox.

Related Keys: none




Initial Value: 15

Default Value: 15

Example: /*/popserv/lockTimeout: [15]

Description: Path on the file system to the directory to write server log files. This directory will contain very large amounts of data, so it is important that it be on a file system with substantial free space. The logDir key can be an absolute path or a path relative to the InterMail installation directory.

Related Keys: none



Possible Values: a valid directory path name

Initial Value: log

Default Value: log

Example: /*/common/logDir: [log]



��)��)��

Description: Domain name to add automatically to usernames when logging in through the POP and IMAP servers. Typically, loginDefaultDomain should be null.

When a login connection is attempted without an explicit domain (e.g., login user versus login user@domain), and the IP address for the connection is not listed among the values of the loginDefaultDomainTable configuration key, then the value of the this key is automatically appended to the username as the default domain.

Related Keys: none




Initial Value: null

Default Value: null

Example: /*/common/loginDefaultDomain: [software.com]

Configuration Keys


��)��)��$��

Description: Provides a list of default domains based on the IP address to which the POP connection is made.

Multiple entries are allowed; however, each entry must appear on its own line, between its own set of square brackets and each entry must be in the form:

<IPaddress>:<domain>

where:

• <IPaddress> is the IP address from which the POP connection is made

• <domain>the default domain associated with users connecting from that IP address

The loginDefaultDomainTable key provides flexibility. If a POP server machine has multiple IP interfaces or if one of the interfaces has multiple IP aliases, then clients can connect to different IP addresses and get different default domains.

For example, if the entries for the key were as follows:

[128.123.46.22:software.com][128.123.46.23:hardware.com]

A user logging in as “joe” to IP address 128.123.46.22 would be recognized as [email protected], while a user logging in as “joe” to IP address 128.123.46.23 would be recognized as [email protected].

Note: This table is only consulted if the login name contains no @ sign. If a match is found among the entries in the table the corresponding default domain is added to the end of the login name with an @ before it. If none of the IP addresses match, then the value of the loginDefaultDomain key is used. If that value is not specified, no default domain is added.

Related Keys: LoginNameConvertFrom, loginNameConvertTo



Possible Values: one or more entries, each consisting of an IP address, a colon, and a valid domain name

Initial Value: null

Default Value: null

Example: /*/common/loginDefaultDomainTable: [128.123.46.22]



��

Description: A list of regex substitution filters that are applied, in sequence, to every name supplied in a POP authentication query before the name is looked up in the Directory database.

The value of the loginFilter configuration key may include multiple entries, but each entry must appear on a separate line contained within its own set of square brackets.

Entries should be in the form:

s/pattern/replace/optss/pattern2/replace2/opts2 ...

where the / can be any single character not used in pattern or replace, and opts can be empty or a string containing g and/or i (similar to Perl).

Values are separated by whitespace and/or punctuation.

Examples:

s%xxx%yyy%is/^(.*)$/Z-\1/i

The pattern argument is a POSIX regular expression. The replace string can be simple text, or it can contain expressions of the form \N, where N is a digit. If the pattern contains at least N parenthesized groups, then the text that matched the Nth group in the input will be substituted for the corresponding \N in the output.

Note: If the IMDIAG environment variable contains popFilter=3 before starting the imdirserv process, trace output will be generated that may be useful in researching issues surrounding use of this configuration key,

Related Keys: none



Possible Values: a string with multiple substitution expressions

Initial Value: null

Default Value: null

Example: /*/imdirserv/loginFilter: [s%xxx%yyy%i]

Configuration Keys


��'��

��'��$�

Description: List of characters to convert in a login name.

Related Keys: loginNameConvertTo



Possible Values: any valid character or characters

Initial Value: null

Default Value: null

Example: /*/common/loginNameConvertFrom: []

Description: Character used to replace characters in a login name that match those specified in loginNameConvertFrom.

Related Keys: loginNameConvertFrom



Possible Values: any valid character or characters

Initial Value: @

Default Value: @

Example: /*/common/loginNameConvertTo: [@]



��.�!'��

��

Description: Indicates whether to log the creation of mailboxes “on the fly.” When true, the server that created the mailbox also records the automatic mailbox creation in the log. When false, it does not log automatic mailbox creation.

Related Keys: none

Servers Affected: POP server, IMAP server, MTA



Initial Value: true

Default Value: true

Example: /*/common/logMailBoxCreation: [true]

Description: Determines the behavior of the named pipe that transmits log file information. If the value is set to zero, a named pipe will not be created. If the value is set to 1, a named pipe is created if necessary, and log entries transmitted to the pipe whether or not there is a reader on the pipe. If the value is set to 2, the named pipe is blocked until there is a reader.

If you plan to use a named pipe, the recommended value is 1.

Related Keys: none



Possible Values: 0, 1, or 2

Initial Value: 0

Default Value: 0

Example: /*/common/logNamedPipeMode: [1]

Configuration Keys


��&��0�

��$��

Description: Adjusts (only upward) the size of the recorder buffer used for the log file. A value of ‘0’disables the recorder buffer (but still writes to file).

Related Keys: none.


Change Impact: Trivial, no server restart required

Possible Values: Any non-negative integer



Example: /*/common/logRecorderSize: [100000]

Description: Redirects the logging of serious InterMail conditions to the system log (syslog on UNIX and the event viewer on NT). This key will affect events that are listed as Fatal and Urgent.

Related Keys: none






Example: /*/common/logToSystem: [false]



��&��"��

Description: Name of a host to use if there is no default route in mailRoutingTable. Note that the system uses the routes of addresses with explicit routes even if there is a value for this option.

Related Keys: mailRoutingTable




Initial Value: null

Default Value: null

Example: /*/mta/mailRoutingHost: [firewall.software.com]

Configuration Keys


��&��$��

��,��"��

Description: Series of instructions to route messages to a machine other than the destination specified in their address.

Normally this is useful in situations where a firewall prevents direct access to the destination mail server, or when mail needs to pass through a gateway to another network (such as a UUCP network).

Entries in the table consist of a host name, followed by a colon, and then another host name. You can also use a pattern, followed by a colon, and then a hostname.

Any mail addressed to a host that matches the pattern to the left of the colon goes to the host listed immediately after the colon.

Note: You may also include instructions in the mailRoutingTable entry to indicate header and domain rewriting for outgoing mail.

Related Keys: none



Possible Values: See the Chapter 9 of the InterMail Kx Operations Guide.

Initial Value: null

Default Value: null

Example: /*/mta/mailRoutingTable: [paris:paris.software.com] [domain:gateway.otherdomain]

Description: The name of the host designated as the SNMP master agent.

Related Keys:

Servers Affected: SNMP server.


Possible Values: Any hostname

Initial Value: null

Default Value: null

Example: /*/common/masterAgentHost: [paris]



��!,��&��

��!.��'��

Description: Server-wide limit on the size of any mailbox “property” that can be stored in the IM_AutoReplyMessage table. Size is expressed in kilobytes.

The maxAutoReplyMsgLenKb configuration key limits the size of the vacation message used for vacation-mode and auto-reply. In addition, this key controls the size of the address book and signature text managed by WebEdge for each account.

Related Keys: none


Change Impact: Trivial.


Initial Value: 100

Default Value: 100

Example: /*/mta/maxAutoReplyMsgLenKb: [377]

Description: Maximum number of invalid SMTP commands that a client may transmit during a session. If a connecting client issues more than this number of invalid SMTP commands, the MTA will close the connection to that client.

Related Keys: none



Possible Values: any integer greater than or equal to 3

Initial Value: 10

Default Value: 10

Example: /*/mta/maxBadCommands: [10]

Configuration Keys


��!.��

��!.��,��

Description: Number of bad password attempts allowed before dropping a client connection.

This key limits the number of bad password attempts allowed before a client connection is dropped. Setting the value to 0 will disable this feature.

Related Keys: none




Initial Value: 3

Default Value: 3

Example: /*/imapserv/maxBadPassword: [3]/*/popserv/maxBadPassword: [3]

Description: Maximum number of IP addresses to track for violations of the POP or IMAP password policy.

Each time a failed authentication occurs, InterMail stores the IP address of the client that issued the incorrect login information. It logs additional entries until the size of the list reaches maxBadPasswordAddrs. When it reaches this limit, it logs this fact and resets the list to zero.

A value of 0 (zero) means the system will not maintain a list of the IP addresses of clients that issued incorrect login information.

Related Keys: none






Example: /*/common/maxBadPasswordAddrs: [10240]



��!.��)��

��!.��-��

Description: Maximum delay time (in seconds) for POP or IMAP authentication attempts.

maxBadPasswordDelay relates to badPasswordDelay , which defines an enforced delay period between failed authentication attempts. Delays specified in badPasswordDelay are cumulative up to the limit defined by maxBadPasswordDelay.

A value of 0 (zero) means there is no delay; however you should not disable this feature by setting its value to 0. Instead, set the values of the maxBadPasswordAddrs and maxBadPasswordUsers configuration keys to 0.

Related Keys: badPasswordDelay




Initial Value: 90

Default Value: 90

Example: /*/common/maxBadPasswordDelay: [60]

Description: Maximum size for a list of accounts that have given an incorrect password. When the list reaches the size limit, it logs the event and resets the list size to zero.

A value of 0 (zero) means the system will not maintain a list accounts for which an incorrect password was given.

Related Keys: none






Example: /*/common/maxBadPasswordUsers: [10240]

Configuration Keys


��!.��

��!)��)��

Description: Maximum number of unread bounceQuotaNotice messages there can be in any one mailbox.

A setting of -1 (or any other negative number) means there is no limit to the number of unread bounce quota messages in a mailbox.

A setting of zero means that users will not receive any bounceQuotaNotice messages.

Related Keys: none



Possible Values: any integer

Initial Value: 20

Default Value: 0

Example: /*/mss/maxBounceNotices: [3]

Description: Maximum number of recipients for a message delivered directly from memory.

The system immediately secures any message with more than this number of recipients by writing it to the spool directory and signaling acceptance to the sending server.

Related Keys: none




Initial Value: 15

Default Value: 15

Example: /*/mta/maxDirectDelivery: [15]



��!)��.

��!��

Description: Maximum size (in kilobytes) for a message delivered directly from memory.

The system immediately secures any message larger than this size by writing it to the spool directory and signaling acceptance to the sending server.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mta/maxDirectKB: [120]

Description: Maximum number of folders allowed within a user’s mailbox.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mss/maxFolders: [100]

Configuration Keys


��!��"��

��!��(

Description: Maximum number of MTA hops allowed for a message.

A message “hops” when it moves from one MTA to another. Hops are measure by the number of Received: lines in the message header.

The number of hops is significant because messages handled many times by many mail servers may be in a mail loop.

When InterMail receives a message handled more than the defined number of times, it stops delivery of the message, and handles it as Error-Actions/mtaMaxMtaHopCountExceeded defines.

Related Keys: Error-Actions/mtaMaxMtaHopCountExceeded




Initial Value: 30

Default Value: 30

Example: /*/mta/maximumMtaHops: [30]

Description: Defines the amount of storage in bytes for keywords of a message. Note that there is a one byte overhead for each keyword stored. Modifying this value potentially affects performance.

This should be as small as possible, but large enough to handle what you expect to be the longest keyword settings for a message.

Related Keys: none

Servers Affected: MSS, IMAP server



Initial Value: 255

Default Value: 255

Example: /*/common/maxKeywordLength: [255]



��!��0��.

��!��$�!�'��(�

Description: Maximum size (in kilobytes) of a message that the system is willing to accept from a client (via SMTP).

The system rejects messages greater than this size with a 552 code.

A value of zero indicates unlimited message size.

Related Keys: none




Initial Value: 10240 (10 Mb)

Default Value: 10240 (10 Mb)

Example: /*/mta/maxMessageSizeInKB: [10240]

Description: Maximum amount (in bytes) of message text the IMAP server should try to cache.

Caching message text in the IMAP server reduces the load on the MSS by allowing the IMAP server to handle a series of FETCH requests from an IMAP client.

The default value is one megabyte (1024x1024).

Related Keys: none



Possible Values: Warning! Do not attempt to modify the value of this key.



Example: /*/imapserv/maxMsgTextCache: [1048576]

Configuration Keys


��!��)��'��

��!��&'�$�

Description: Maximum number of messages to deliver to a MSS in a single transaction.

Related Keys: none




Initial Value: 20

Default Value: 20

Example: /*/mta/maxMssDeliverCount: [20]

Description: Maximum number of recipients allowed when the MAIL FROM: address in any message is NULL (“<>”).

Messages sent from the NULL address (such as bounce notices) typically do not include more than one recipient. Messages from the NULL address with more than one recipient are unsolicited commercial e-mail suspects.

A value of zero allows an unlimited number of recipients.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/maxNullSenderRCPTs: [1]



��!��

Description: Number of authentication failures on an account or by an IP Address before dropping connections.

Specifies a limit on the number of authentication failures on a given account or from a particular IP Address before connections are dropped. The recommended minimum setting for this key is 1. Setting this value to 0 will disable this feature.

Related Keys: none




Initial Value: 10

Default Value: 10

Example: /*/common/maxPasswordFailures: [10]

Configuration Keys


��!#��$��"��

Description: Maximum number of hours to keep a message in the queue for deferred outbound mail.

The system queues messages that are not immediately deliverable (for example, mail to a remote host that is temporarily unavailable) for subsequent delivery attempts. These attempts occur regularly at the expiration of the outboundDeferProcessInterval queue processing interval.

After a message has been in the queue for maxQueueTimeInHours days, InterMail assumes that the message is undeliverable and returns the message to its sender.

Internet standards recommend queuing such messages for 4 or 5 days (i.e a setting of 96 or 120). However, you may want to shorten that period if there is a more urgent need to know when the system has not delivered mail.

Related Keys: none



Possible Values: Any non-negative integer representing number of hours.

Initial Value: 96 (4 days)

Default Value: 96

Example: /*/mta/maxQueueTimeInHours: [96]



��!��

��!$(��

Description: Maximum number of simultaneous sessions the POP or IMAP server will support.

When the number of concurrent sessions has reached maxSessions, the server does not accept additional connections.


Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/imapserv/maxSessions: [50]

Description: Limits the number of threads created per process. Recommended values range from 100 to 10000.

Note: This key is only significant for installations that run on IRIX.

Related Keys: none




Initial Value: 2048

Default Value: 2048

Example: /*/common/maxThreads: [2048]

Configuration Keys


��)��

��&��$��

Description: Path on the file system to the directory that contains the message files.

This directory will contain every message for every account stored on a particular host, so it should be on a partition with as much free space as possible.

This configuration key can be an absolute path or a path relative to $INTERMAIL.

Related Keys: none



Possible Values: any valid directory path

Initial Value: set at installation time

Default Value: null

Example: /*/mss/messageFilesDir: [msgfiles]

Description: Enables/disables message tracing for message-reading operations in the MSS.

When true, the MSS writes MsMsgRead and MsMsgRangeRead log entries when it fetches messages for a client.

When false, the MSS does not write MsMsgRead and MsMsgRangeRead log entries.

Related Keys: none






Example: /*/mss/messageReadTracing: [false]



��$��

��

Description: Indicates whether to report message trace notifications in the log files.

This is an important option for debugging and measuring system performance, since it tracks the flow of messages through the InterMail system.

You can set this key independently for any server.

Related Keys: none




Initial Value: MSS: falseremaining servers: true

Default Value: MSS: falseremaining servers: true

Example: /*/mta/messageTracing: [true]

Description: Port on which the Manager server listens for requests to start, drain, stop, and restart servers.

Related Keys: none

Servers Affected: Manager server




Default Value: null

Example: /*/immgrserv/mgrServPort: [5004]

Configuration Keys


��

��)��*��.

Description: How to pre-parse locally delivered mail before delivery to the MSS.

If on, all locally delivered mail is subject to IMAP parsing.

If off, no mail is subject to IMAP parsing.

If imap-only, the only messages subject to IMAP parsing are those destined for local users whose accounts have IMAP delivery enabled.

Related Keys: none



Possible Values: yes, no, true, false, or imap-only

Initial Value: imap-only

Default Value: imap-only

Example: /*/mta/mimeParseMode: [imap-only]

Description: Minimum free disk space (in kilobytes) required for the MTA to continue accepting messages.

If the amount of system disk space is less than the value defined by minFreeDiskSpaceInKB, the MTA temporarily stops accepting messages.

A value of zero indicates no limit.

Related Keys: none






Example: /*/mta/minFreeDiskSpaceInKB: [10000]



��#��$��

Description: Minimum time (in seconds) between attempts to process queued mail for any individual domain. A value of zero means there is no limit.

This key distributes queue processing time among all queues, and prevents a single large queue from consuming a disproportionate amount of available processing time.

minQueueIdleTime operates in conjunction with ouboundDeferProcessInterval, which sets an interval between queue processing intervals. In order to be effective, minQueueIdleTime must be higher than outboundDeferProcessInterval.

For a further discussion of how to use minQueueIdleTime and ouboundDeferProcessInterval, please see Chapter 10 of the InterMail Kx Operations Guide.

Related Keys: outboundDeferProcessInterval





Default Value: 60 (1 minute)

Example: /*/mta/minQueueIdleTime: [900]

Configuration Keys


��&��

��)��$(��

Description: Enables/disables the POP server’s ability to automatically move messages that caused a download error.

If true, and the POP server encounters a message that causes an error, the server moves the message into the .ERROR folder in the account’s mailbox (creating this folder if necessary). The server then checks all other messages in this mailbox to verify that they are retrievable.

If false, the POP server does not move messages when it encounters a download error. This may lead to problems for connecting clients, and require administrator intervention.

The recommended value is true.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/popserv/moveRetrieveErrors: [true]

Description: Maximum number of threads available for the MTA’s Deliverer task.

The Deliverer is responsible for communicating with the MSS to deliver mail destined for a local mailbox.

Related Keys: none




Initial Value: 40

Default Value: 10

Example: /*/mta/msgDelivererNumThreads: [40]



��'��(��0��.

��%��$(��

Description: Size (in kilobytes) of the message file cache on the MSS.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mss/msgFileCacheSizeInKB: [100]

Description: Maximum number of threads available for the MTA Validator task.

The Validator queries the Integrated Services Directory to determine the destination of a message. It also handles errors, and is responsible for examining and rewriting message headers. Therefore, there should be more msgValidatorNumThreads than dirRmeConnections.

Related Keys: dirRmeConnections




Initial Value: 80

Default Value: 10

Example: /*/mta/msgValidatorNumThreads: [80]

Configuration Keys


��.��

��)��$��

Description: The base port number for MSS processes on a host. If a single host runs multiple MSS processes, these processes will use a contiguous set of port numbers that begin at the port number given here.

Related Keys: none.



Possible Values: Any unused port number. If multiple MSS processes will be run on the same system, this port should have enough contiguous unused ports after it.

Initial Value: Port number set during installation.

Default Value: 5089

Example: /*/mss/mssBasePort: [5089]

Description: How long (in seconds) the MTA should wait for the MSS to respond before timing out. This applies only to multiple delivery operations.

Related Keys: none




Initial Value: 1200

Default Value: 1200

Example: /*/mta/mssDeliverTimeoutSecs: [1200]



��

��!��

Description: Path on the file system to the MTA spool directory. The system stores deferred messages in this directory.

Deferred mail can take up significant disk space, so this directory should be on a drive partition with large amounts of free space.

mtaSpool can be an absolute path or a path relative to the InterMail installation directory.

Related Keys: none



Possible Values: a valid file path

Initial Value: spool

Default Value: spool

Example: /*/mta/mtaSpool: [spool]

Description: Controls the numbering of mutexes created by the InterMail servers.

Warning! This key should not be modified except in conjunction with vendor or technical support.

Related Keys: none






Example: /*/common/mutexSerialNumbering: [false]

Configuration Keys


��#��

Description: Text of the near-quota notification message.

The entry for this key may include macros, enclosed in angle brackets (< >). Real text replaces the macros before sending the message. Supported macros include:

• <Available_Resource>

indicates the unused portion of a user’s quota

• <Requested_Resource>

indicates the quota exceeded (for example, maximum mailbox size, maximum message size, or maximum number of mes-sages in a mailbox)

• <User_Quota>

indicates the user’s total quota

You can use these additional macros to generalize this facility to other quotas:

• <Resource_Name>

indicates the name of the resource (such as message bytes)

• <Resource_Type>

indicates a type for the resource (such as bytes)

• <Resource_Referent>

indicates the object referenced (such as mailbox)

Related Keys: none




Initial Value: From: <HWM_Notice_From>Subject: <HWM_Notice_Subject>Date: <HWM_Notice_Date>Your mailbox is over the high water mark.Please delete some messages from your mailbox!

Default Value: Please delete some messages from your mailbox.

Example: /*/mss/nearQuotaNotice: [Please delete some mail.]



��$��

��)��

Description: Timeout (in seconds) for network operations.

Related Keys: none




Initial Value: for the imconfget command: 30for the imconfcontrol: 30for all servers: 240

Default Value: 120

Example: /*/common/netTimeout: [240]

Description: Directory containing the NLS (National Language Support) catalogs. These catalogs contain message strings for multiple language support.

Related Keys: none



Possible Values: a valid full file path

Initial Value: nlslib

Default Value: null

Example: /*/common/nlsDir: [nlslib]

Configuration Keys


��)��

��!)��

Description: Email is delivered to the Internet and then delivered appropriately by DNS. This requires having an in-MTA and an out-MTA.

Related Keys: none






Example: /*/mta/noLocalDelivery: [false]

Description: The number of files used to store the mbox database.

Related Keys:



Possible Values: any non-negative integer.

Initial Value: 8

Default Value: 8

Example: /*/mss/numMboxDbFiles: [8]



��)��

��-��).��

Description: The number of files used to store the msgid database.

Related Keys:



Possible Values: any non-negative integer.

Initial Value: 8

Default Value: 8

Example: /*/mss/numMsgIdDbFiles: [8]

Description: The number of db files to use when splitting the dircache database

($INTERMAIL/db/dircache).

Related Keys: none



Possible Values: any non-negative integer (including 0).

Initial Value: 1

Default Value: 1

Example: /*/imdirserv/numUserDBFiles: [1]

Configuration Keys


��)��+��

��)��

Description: Initial amount of time (in seconds) to wait before processing the queue of mail deferred for external delivery.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/outboundDeferProcessInitialWait: [0]

Description: Processing interval (in seconds) for mail deferred for external delivery.

When this number of seconds have elapsed, the MTA attempts to send messages that it had previously deferred.

Related Keys: none




Initial Value: 300

Default Value: 300

Example: /*/mta/outboundDeferProcessInterval: [300]



��)��

��6��

Description: Path on the file system to the directory containing pid files.

These pid files store the UNIX process IDs of the InterMail processes that are running. The value of pidDir can be an absolute path or a path relative to the $INTERMAIL.

Related Keys: none



Possible Values: a valid directory path

Initial Value: tmp

Default Value: tmp

Example: /*/common/pidDir: [tmp]

Description: Port number the POP server uses to listen for incoming POP3 connections.

Warning! Changing the value from the standard POP3 port (110) is not advisable as this value corresponds to the RFC standard (see RFC 821).

Related Keys: none




Initial Value: 110

Default Value: 110

Example: /*/popserv/pop3Port: [110]

Configuration Keys


��*��$��

��!"��

Description: Maximum number of seconds a socket can hold a pop lock on a mailbox without any IO to that mailbox.

Related Keys: lockTimeout (pop server version)



Possible Values: (integer) 0 ... MAX_INT

Initial Value: 240 seconds

Default Value: 90 seconds

Example: /*/mss/popLockIdleTimeout: [90]

Description: Name of the host that handles POP connections for unknown POP login names.

The typical use is during migration to InterMail from another mail system, and allows migrating accounts over time. If there is no proxy host defined, the POP server returns an error to a connecting client when that client sends an unknown POP login name.

Related Keys: popProxyPort



Possible Values: any valid hostname

Initial Value: null

Default Value: null

Example: /*/popserv/popProxyHost: [jupiter.accordance.com]



��!��

7��

Description: POP port to use for the host specified in popProxyHost.

Related Keys: popProxyHost



Possible Values: the port on which the POP server on popProxyHost is listening

Initial Value: 110

Default Value: 110

Example: /*/popserv/popProxyPort: [110]

Description: Maximum number of messages that one MTA can handle at one time.

This distributes the load among multiple MTAs by restricting the amount of work given to any one server.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mta/queueSplitFactor: [100]

Configuration Keys


��"��'��

��"��$$��

Description: Indicates the number of bad RCPT TO: commands from the same IP within a window of time that causes that IP to be labeled a RCPT TO: harvester.

Related Keys: none



Possible Values: 1...INT_MAX

Initial Value: 30

Default Value: 30

Example: /*/mta/rcptHarvesterCount: [30]

Description: Once an IP a source of RCPT TO: harvesting is labled, this key indicates how long (in minutes) connections are blocked from that IP.

Related Keys: none


Change Impact: tivial


Initial Value: 60

Default Value: 60

Example: /*/mta/rcptHarvesterTTLMinutes: [60]



��!"��

��"��$$��

Description: The maximum number of harvesters and potential harvesters to track.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mta/rcptMaxHarvesters: [100]

Description: Once there is one bad RCPT TO: from a given IP, this key indicates how long (in minutes) that IP is tracked for more bad RCPT TO:’s and consided as part of the same harvesting attack. (Since the entries expire periodically, and the expired thread runs every rcptPotentialHarvesterTTLMinutes minutes, an entry could live 1.5 times longer than rcptPotentialHarvesterTTLMinutes).

Related Keys: none




Initial Value: 3

Default Value: 3

Example: /*/mta/rcptPotentialHarvesterTTLMinutes: [3]

Configuration Keys


��4��)��

��4��,��

Description: Specially configured DNS server to use when looking for domains to reject.

Related Keys: none




Initial Value: null

Default Value: null

Example: /*/mta/rejectDnsServer: [pluto]

Description: Specifies whether or not senders are required to provide a RFC 821 compliant MAIL FROM address.

If rejectInvalidFromAddr is set to true, senders must provide a RFC 821 compliant address with the MAIL FROM command in order for it to be accepted. Note that in the case of rejection, a reply code of blockReplyCode with the text blockReplyText is sent to the sender.

If rejectInvalidFromAddr is set to false, no requirement is made that senders must provide an RFC-821 compliant MAIL FROM address.

If the user uses an invalid address in the MAIL FROM: header,

as in joe@software,com or joe@foo@bar@baz (where there is a syntax error in the specification of an SMTP address), normally the FROM address is changed to < >. If rejectInvalidFromAddr is true, mail will not be sent from an invalid MAIL FROM: address.

Related Keys: blockReplyCode, blockReplyText






Example: /*/mta/rejectInvalidFromAddr: [false]



��4��.��,��

��4��.��)��

Description: If set to true, the sender address must parse correctly (refer to RFC821 for address rules) to be accepted (refer to RFC821 for the definition of invalid).

If not accepted, the message is rejected with a 550 response code and the text Sender address is invalid.

Related Keys: The complete set of reject anti-spam keys that define rules for rejecting senders are:

/*/mta/rejectSenderBadAddress: [false]

/*/mta/rejectSenderBadDomain: [false]

/*/mta/rejectSenderIPDomain: [false]

/*/mta/rejectSenderNoDomain: [false]






Example: /*/mta/rejectSenderBadAddress: [false]

Description: Indicates whether to reject a sender’s mail because of a bad domain.

If true, the sender’s domain must exist in DNS or it will reject the message.

Related Keys: none






Example: /*/mta/rejectSenderBadDomain: [false]

Configuration Keys


��4��)��

��4��)��

Description: Indicates whether senders may provide an IP address instead of a domain in the MAIL command.

If true, senders may not give an IP address for their domain in the MAIL command.

If false, senders may give an IP address for their domain in the MAIL command.

Related Keys: none






Example: /*/mta/rejectSenderIpDomain: [false]

Description: Indicates whether senders must provide a domain in the MAIL command.

If true, senders must provide a domain in their MAIL command in order for the system to accept it.

If false, it is not necessary that senders give a domain in the MAIL command.

Related Keys: none






Example: /*/mta/rejectSenderNoDomain: [false]



��)��,��

��)��)��

Description: List of domains to relay messages to, regardless of restrictions on the source of the messages.

Including domains in relayDestAllowList implies that no other domains receive mail that your relay source policies restrict.

relayDestAllowList may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: none



Possible Values: a valid domain name

Initial Value: null

Default Value: null

Example: /*/mta/relayDestAllowList:

[accordance.com]

[software.com]

Description: Destination domains to deny restricted relay mail.

The system will not send any message from a restricted source (according to your relay source policies) to these domains. Including domains in relayDestDenyList implies that all other destination domains receive relay mail regardless of source restrictions.

relayDestDenyList may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: none



Possible Values: a valid domain name

Initial Value: null

Default Value: null

Example: /*/mta/relayDestDenyList: [accordance.com]

Configuration Keys


��"��

��)��/*

Description: Host to relay mail addressed to unknown users.

This option is useful during migration from an existing mail system, and allows you to migrate accounts in batches while the InterMail system is up and running.

Related Keys: none




Initial Value: null

Default Value: null

Example: /*/mta/relayHost: [jupiter]

Description: Indicates whether to include local mail domains in the relaySourceDomainList list of domains.

relayLocalDomainsOk applies only if relaySourcePolicy restricts relay except for those hosts, domains, and users specified in allowListed.

When true, the system relays without restriction all messages whose return address includes a local mail domain.

Related Keys: relaySourcePolicy, relaySourceDomainList, allowListed




Initial Value: true

Default Value: true

Example: /*/mta/relayLocalDomainsOk: [true]



�� !��

Description: Indicates whether to verify local senders before allowing relay.

When true, and the return address of a submitted message includes a local mail domain, InterMail confirms the existence of the sender in the Integrated Services Directory. If the address exists in the ISD, it allows relay; if the address does not exist, it denies relay.

relayLocalMustExist overrides relayLocalDomainsOk.

Related Keys: none






Example: /*/mta/relayLocalMustExist: [false]

Configuration Keys


��!&'�$�

Description: Defines the maximum number of recipients allowed, not the minimum, before checking the relay restrictions.

For example, if the value of the relayMaxRCPTS configuration key were set to 3, then all messages with less than three recipients would be exempt from established relay restrictions, however all messages with three or more recipients would be subject to those restrictions.

The recommended value is 0 because it causes all messages to go through relay checks.

Related Keys: relayLocalMustExist

relayDestAllowList

relayDestDenyList

relaySourcePolicy

relaySourceDomainList

relayLocalDomainsOK

relaySourceRemoteIPList

relaySourceLocalIPList

relayNullRestricted




Initial Value: 0

Default Value: 0

Example: /*/mta/relayMaxRCPTs: [0]



��&��

��&��'��

Description: Indicates whether to restrict messages that have a null (<>) return address.

relayNullRestricted applies only if relaySourcePolicy allows relay except from specified host, domains, and users (denyListed or allowListed).

If false, there are no restrictions on mail with a null source address.

Related Keys: relaySourcePolicy, allowListed, denyListed




Initial Value: true

Default Value: true

Example: /*/mta/relayNullRestricted: [true]

Description: Error code to return in response to RCPT TO if the number of recipients reaches relayMaxRCPT.

Related Keys: none



Possible Values: an error code

Initial Value: 550

Default Value: 550

Example: /*/mta/relayReplyCode: [550]

Configuration Keys


��&��$�!�

��)��

Description: Error text to return in response to RCPT TO if the number of recipients has reached relayMaxRCPTs . It replaces the word DOMAIN (all caps) with the domain name.

Related Keys: none




Initial Value: Relaying mail to DOMAIN is not allowed

Default Value: Relaying mail to DOMAIN is not allowed

Example: /*/mta/relayReplyText: [relaying mail to DOMAIN is not allowed]

Description: List of domains to apply the relay policy defined by relaySourcePolicy.

When the return address of a message (defined by the MAIL FROM command) includes a domain listed in relaySourceDomainList, relaySourcePolicy determines whether to restrict or allow the message .

relaySourceDomainList may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.

Related Keys: relaySourcePolicy



Possible Values: a fully qualified domain name or a domain name with a wildcard prefix

Initial Value: null

Default Value: null

Example: /*/mta/relaySourceDomainList: [acme.com][newday.com]



��

Description: List of local IP addresses to apply the relay policy defined by relaySourcePolicy. When a message is destined for an MTA containing an IP address shown in this list, the system restricts or allows this message based on the value of relaySourcePolicy for this host.





Initial Value: null

Default Value: null

Example: /*/mta/relaySourceLocalIpList: [10.3.21.0][10.20.20.0]

Configuration Keys


��

Description: Defines the overall relay policy.

The available policies are:

• allowAll: Allow all relay

• denyListed: Allow relay except from specific users/hosts/domains

• allowListed: Deny relay except from specific users/hosts/domains

• denyAll: Deny all relay

When defining relay restrictions, you should always start by setting (or verifying) the value of this key.

Related Keys: relaySourceRemoteIPList, relaySourceLocalIPList



Possible Values: allowAll, denyAll, allowListed, denyListed

Initial Value: allowAll

Default Value: allowAll

Example: /*/mta/relaySourcePolicy: [denyAll]



��&��

��

Description: List of remote IP addresses to apply the relay policy defined by relaySourcePolicy. When the system receives a message from a host whose IP address is on this list, the system restricts or allows the message based on relaySourcePolicy.

The relaySourceRemoteIpList may include multiple entries, but each entry must appear on a separate line within its own set of square brackets.




Possible Values: a valid IP address

Initial Value: null

Default Value: null

Example: /*/mta/relaySourceRemoteIpList: [10.20.20.0]

Description: How much time (in seconds) a server waits to examine its activity statistics, and write the changed values to a .stat file.

Related Keys: none




Initial Value: 180

Default Value: 180

Example: /*/common/reportParamsInterval: [180]

Configuration Keys


��7��'��

��7��,��(

Description: Servers should terminate lines with CRLF. Setting requireCRLF to true prevents bare line feed characters from terminating lines.

Related Keys: none






Example: /*/mta/requireCrLf: [false]

Description: Specifies whether SMTP clients that have SMTP authentication enabled must provide the appropriate SMTP validation before they are allowed to authenticate. If this key is set to true, SMTP authentication is necessary. Without it, the system will reject clients’ mail.

Note: This applies only when checkAuthentication is set to true, and when AUTH_LOGIN is used.

Related Keys: checkAuthentication






Example: /*/mta/requireSecureAuth: [false]



��)��

��1��"��

Description: Indicates whether to rewrite domains of headers on incoming messages.

If true, it tests headers of incoming mail for domain rewriting. Only those headers indicated in rewriteHeaderList are eligible for domain rewriting.

If false, it does not test headers for domain rewriting on incoming mail.

See Chapter 9 of the InterMail Kx Operations Guide for a complete discussion of the InterMail routing and rewriting rules.

Related Keys: rewritePrimary






Example: /*/mta/rewriteDomains: [true]

Description: List of headers on outgoing mail to rewrite headers.

Related Keys: none



Possible Values: the name(s) of any headers that may contain addresses

Initial Value: null

Default Value: null

Example: /*/mta/rewriteGatewayHeaderList: [To:]

Configuration Keys


��"��

��!��"��

Description: List of headers on incoming mail to rewrite headers. If a null value is specified, headers are not rewritten.

Related Keys: none



Possible Values: the name(s) of any headers that may contain addresses

Initial Value: null

Default Value: null

Example: /*/mta/rewriteHeaderList: [To:][From:]

Description: Indicates whether to restrict rewriting headers for incoming mail based on the number of mail servers that have already handled the message.

If a message has passed through more than this number of MTAs, then the system does not rewrite its header.

The default setting of 1 means that the system does not rewrite headers if the message has passed through more than one SMTP server on its way to the InterMail MTA.

Related Keys: rewriteOnlyLocal, rewriteHeaderList, rewriteGatewayHeaderList, rewriteSaveOrig




Initial Value: 1

Default Value: 1

Example: /*/mta/rewriteMaxMtaHops: [2]



��/��

��

Description: Indicates whether to restrict header rewriting for incoming mail based on the sender’s identity.

If true, it only rewrites message headers if the sender address (from the SMTP envelope) is in a known domain in the Integrated Services Directory.

If false, it rewrites headers regardless of the sender address.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/rewriteOnlyLocal: [false]

Description: Indicates whether to rewrite the primary address for headers on incoming messages.

If true, it tests the headers of incoming mail for primary address rewriting. Only those headers indicated in rewriteHeaderList are eligible for primary address rewriting. If primary address rewriting is necessary, it replaces the address in the header with the user’s primary address.

If false, it does not test the headers of incoming mail for primary address rewriting.

See Chapter 9 of the InterMail Kx Operations Guide for a complete discussion of the InterMail routing and rewriting rules.

Related Keys: rewriteDomains






Example: /*/mta/rewritePrimary: [true]

Configuration Keys


��/��

��,��

Description: Indicates whether to preserve original addressing information when header rewriting occurs.

If true, it saves the original header information in an “X-Original” header within the message.

Related Keys: none




Initial Value: true

Default Value: true

Example: mta/rewriteSaveOrig: [true]

Description: This is a list of IP addresses or IP masks which are allowed to connect to RME ports (such as the MSS port or the Directory RME port, etc). If a client connects from an address that is not in this list, the connection will be refused and a NioConnNotAllowed error will be logged.

Related Keys:



Possible Values: a list of IP addresses or IP masks (in the same format as blockTheseIPs)

Initial Value: null

Default Value: null

Example: /*/common/rmeAccessList: [ ]



��'��$��

��)�

Description: Network timeout value (in seconds) for RME connection attempts.

If it does not receive a response to the connection attempt within this period, the connection fails with an NioTimeout event error.

Related Keys: none




Initial Value: 10

Default Value: 10

Example: /*/common/rmeConnectTimeout: [10]

Description: Number of times per day that InterMail logs roll over to new log files. Logs roll over at equally spaced intervals. For example, if rolloversPerDay is 24, logs will roll over once per hour.

rolloversPerDay can apply individually to any server. You may want to vary the number of rollovers per day by server and establish a larger number of daily rollovers for servers that record events more frequently.

Related Keys: none




Initial Value: 1

Default Value: 0

Example: /*/common/rolloversPerDay: [1]

Configuration Keys


��$��8��

&$��/��(��

Description: Offset (in seconds) from midnight GMT at which log rollovers start.

You should set this for your time zone prior to bringing InterMail online.

An offset of 18,000 (5 x 60 x 60) would specify midnight EST.

rolloverTimeZero can apply to any server, but should apply to all servers in common using the following entry:

/*/common/rolloverTimeZero

Otherwise, it might be difficult to remember the different time periods for the different servers.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/common/rolloverTimeZero: [18000]

Description: Controls whether the server continues to run if shared memory is not available.

WARNING! Do not modify or remove this key since changing its value may cause the servers to fail to operate.

Related Keys: RTMIDisable


Change Impact: Do not change the value of this key. Changing the value of this key may cause the servers to fail to operate.




Example: /*/common/RTMIabortOnSharedMemoryFail:[false]



&$��)��

��)��

Description: Enables and disables the RTMI system..

WARNING! Do not modify or remove this config key since changing its value may cause the servers to fail to operate.

Related Keys: RTMIabortOnSharedMemoryFail


Change Impact: Do not change the value of this key. Changing the value of this key may cause the servers to fail to operate.


Initial Value: true

Default Value: true

Example: /*/common/RTMIDisable:[true]

Description: Working directory for the InterMail servers.

Related Keys: none




Initial Value: /var/tmp

Default Value: /tmp

Example: /*/common/runDir: [/var/tmp]

Configuration Keys


��/��"��

��(��

Description: Scanning for volumes of old mail can be resource intensive since each piece needs to be inspected. This key allows the user to specify how often to check the mail that has been in the system for more than the interval specified by the maxQueueTimeInHours configuration key.

If it were set to 24 hours, then we would check each outbound domain once a day for mail that was older than maxQueueTimeInHours.

Related Keys: maxQueueTimeInHours



Possible Values: any non-negative integer representing number of hours

Initial Value: 24

Default Value: 24

Example: /*/mta/scanOldMessagesIntervalInHours: [24]

Description: Maximum line length to allow before rejecting an SMTP server’s response to our commands.

RFC821 defines the minimum line length as 512, and the maximum line length as 1000.

If zero, there is no limit. However, this would allow a hostile server to force the MTA to run out of memory.

Related Keys: none




Initial Value: 1000

Default Value: 1000

Example: /*/mta/serverLineLengthLimit: [1000]



��$(��*��0��.

��$��

Description: Size (in kilobytes) of the stack used by MSS threads.

Related Keys: none




Initial Value: 64

Default Value: 0

Example: /*/mss/serverThreadStackSizeInKB: [128]

Description: Amount of time (in seconds) the Configuration server waits for a response. If the server does not receive a response within the serverTimeout time, it will abandon its request and log an error to standard error.

Related Keys: none




Initial Value: 30

Default Value: 30

Example: /*/imconferv/serverTimeout: [30]

Configuration Keys


��$��

��+��$��

Description: Maximum number of lines to allow before rejecting an SMTP server’s response to the MTA’s commands.

If zero, there is no limit. However, this would allow a hostile server to force the MTA to run out of memory.

Related Keys: none




Initial Value: 100

Default Value: 100

Example: /*/mta/serverTotalLinesLimit: [100]

Description: Indicates whether to print InterMail events to stderr.

By default, the InterMail servers do not report events to stderr, however you can force the servers to print all events of severity level Warning and above by setting servWarnToStderr to true.

Related Keys: none






Example: /*/common/servWarnToStderr: [true]



�(��)��

��

Description: This directory is used to build the path to the nlslib directory during application (server) startup.

Related Keys: none.




Initial Value: The install directory specified at installation time.

Default Value: null

Example: /*/common/sharedDir: [/imail/imail]

Description: Enables/disables message sidelining.

If true, messages that violate sidelineNumRcpts or sidelineNullToMany move to the sideline directory within the queue directory.

Note: Sidelined messages should be reviewed, then deleted or reprocessed (via the immsgprocess command) depending upon their legitimacy.

Related Keys: none






Example: /*/mta/sidelineMessages: [true]

Configuration Keys


��$��

��&��

Description: Indicates whether to sideline messages that arrive from the empty (null) address,< >, if destined for more than a single recipient. If true, the MTA sidelines messages that meet these criteria for later review.

Related Keys: none






Example: /*/mta/sidelineNullToMany: [true]

Description: Maximum number of allowable recipients for a single message before sidelining it as possible unsolicited commercial e-mail.

If zero, it disables this feature.

Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/sidelineNumRcpts: [1000]



��&��'��

��,��$(��

Description: Maximum number of recipients allowed over a given connection before sidelining messages.


Related Keys: none




Initial Value: 0

Default Value: 0

Example: /*/mta/sidelineNumRcptsPerConnection: [0]

Description: Maximum number of threads for the MTA’s SMTP server task, the task responsible for receiving incoming messages.

Related Keys: none



Possible Values: an integer from 1 to 1000

Initial Value: 10

Default Value: 10

Example: /*/mta/smtpAcceptNumThreads: [10]

Configuration Keys


��)��$(��

��

Description: Maximum number of threads for the SMTP Client task.

Defines the number of threads allowed for processing outgoing mail.

There is a separate pool (defined by smtpQueueProcessNumThreads) for queue processing.

Related Keys:



Possible Values: an integer from 1 to 1000

Initial Value: 10

Default Value: 10

Example: /*/mta/smtpDeliverNumThreads: [10]

Description: Port on which the MTA listens for incoming SMTP connections.

Note: Changing this value from the standard SMTP port (25) is not advisable.

Related Keys: none




Initial Value: 25

Default Value: 25

Example: /*/mta/smtpPort: [25]



��#��.��*��'��

��#��$(��

Description: Number of buckets in the spool/SMTP-Deliver directory. These buckets store the messages queued for delivery to external sites.

Related Keys: none




Initial Value: 101

Default Value: 101

Example: /*/mta/smtpQueueBucketCount: [101]

Description: Maximum number of threads for the MTA’s Queue Client task. This task is responsible for processing outgoing mail that was previously in a queue.

Related Keys: none




Initial Value: 10

Default Value: 10

Example: /*/mta/smtpQueueProcessNumThreads: [10]

Configuration Keys


��&��$��

��'��(�,��

Description: The amount of time to wait between reconnection attempts if the SNMP master agent is unavailable (specified in seconds). During this interval, the SNMP thread sleeps and then attempts to reconnect against the SNMP server (snmpdm), immediately after having lost its connection to snmpdm.

Related Keys: none

Servers Affected: SNMP server



Initial Value: 15

Default Value: 15

Example: /*/common/snmpReconnectNapTime: [15]

Description: Lifetime (in seconds) of an SSL session cache entry. The system expires entries older than the number of seconds specified.

Related Keys: none




Initial Value: 7200

Default Value: 7200

Example: /*/popserv/sslCacheAgeSeconds: [7200]



��'��(�.��*��

��'��(�.��*��

Description: Defines the maximum number of entries in each bucket of the SSL session cache. If a bucket reaches the maximum number, then the first entries are removed to make room for the new entries.

Related Keys: none




Initial Value: 1000

Default Value: 1000

Example: /*/imapserv/sslCacheBucketLen: [1200]

Description: Number of buckets in the SSL session cache.

Related Keys: none




Initial Value: 499

Default Value: 499

Example: /*/popserv/sslCacheBucketNum: [499]

Configuration Keys


��'��'(��(,��

��'��

Description: Name of a file containing a PKCS 5 password-encrypted, formatted private key, followed by DER formatted certificates defining the private key and certificate chain for the POP server. The last certificate in the file is the root certificate.

_____Begin and _____End PEM syntax delimit the encrypted private key and certificates. If sslCertChainPathAndFile does not exist, or if there are errors reading the file, then it automatically disables POP server operation on the secure port.

Note: This key is reserved for future use.

Related Keys: none

Servers Affected: MTA, POP server


Possible Values: a valid file path

Initial Value: null

Default Value: null

Example: /*/mta/sslCertChainPathAndFile: [<pathname>]

Description: Specifies the SSL password.

Related Keys: none




Initial Value: InterMail

Default Value: InterMail

Example: /*/mta/sslCertPassword: [InterMail]



��5��

��6��

Description: Controls the listening port for the SSL interface of the IMAP server. To enable SSL processing set this key. Except in unusual cases, the correct value for this key is 993.

Related Keys: none



Possible Values: integer values

Initial Value: 993

Default Value: CFG_ABSURD_PORT_NUMBER

Example: /host/imapserv/sslImap4Port: [993]

Description: Port for secure POP server operation.

If -1, or null, it disables secure POP server operation.

If you assign this key a valid, unused port number, the POP server operates in secure mode on the specified port.

Related Keys: none




Initial Value: 443

Default Value: -1

Example: /*/popserv/sslPop3Port: [443]

Configuration Keys


��

��$��'��(,��

Description: Port number (usually 465) that the MTA listens on for SSL (Secure Socket Layer) connection requests from other MTAs.

When null, or -1, it disables the SSL operation.

If the port specified is 25, then the secure SMTP operates in the mode defined by the SMTP Service Extension for Secure SMTP over TLS (Transport Layer Security). TLS is essentially SSL, but with a negotiation on the standard SMTP port (25) to indicate at the start of the transaction that you want to talk securely. By setting sslSmtpPort to 25, any client that uses the standard SMTP port and is SSL-compliant will negotiate a secure connection.

Related Keys: none




Initial Value: 465

Default Value: -1

Example: /*/mta/sslSmtpPort: [465]

Description: File containing DER formatted trusted certificates.

Each file may contain one or more certificates.

_____Begin and _____End PEM syntax delimits each certificate.

Client and server authentication use these certificates.

Note: This key is reserved for future use.

Related Keys: none

Servers Affected: MTA, POP server


Possible Values: any valid file path

Initial Value: null

Default Value: null

Example: /*/mta/sslTrustedCertPathAndFile: [imail/imail/lib/certs/im_default_certs.txt]



��-��'��(�

��

Description: Indicates whether to use the SSL session cache.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/popserv/sslUseSessionCache: [true]

Description: In InterMail, a named pipe can access all events reported in log files. This key allows you to write .stat files (files that contain statistical information) to a named pipe.

A value of zero (0) indicates not writing statistics to the named pipe.

A value of 1 directs the servers to write statistics to the named pipe.

Related Keys: none



Possible Values: 0, 1

Initial Value: 0

Default Value: 0

Example: /*/common/statNamedPipeMode: [1]

Configuration Keys


��&��0�

��)��

Description: Adjusts the size of the recorder buffer used for the stat file. A value of 0 disables the recorder buffer (but still writes to file).

Related Keys:

Servers Affected: Possibly all servers





Example: /*/common/statRecorderSize: [10240]

Description: Comma-separated list of domain names, used to canonicalize domains.

When converting an unqualified domain to canonical form, it checks the value of this key first for possible expansions.

An entry in this key is necessary when it is not acceptable to canonicalize a domain by blindly appending the domain.

Related Keys: none



Possible Values: one or more valid subdomains separated by commas

Initial Value: null

Default Value: null

Example: /*/mta/subDomains: [hostx.software.com, hosty.software.com]



��'��)��

��'��)��)��

Description: Timeout value (in seconds) for how long the MTA waits to accept SMTP data. If there is no successful input/output after this elapsed interval, the MTA socket shuts down.

Related Keys: none






Example: /*/mta/timeoutClientData: [600]

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the end-of-message character (“.”).

Related Keys: none






Example: /*/mta/timeoutClientDataDot: [900]

Configuration Keys


��'��)��

��'��1��

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when sending message data.

Related Keys: none




Initial Value: 180

Default Value: 300

Example: /*/mta/timeoutClientDataSend: [300]

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the SMTP greeting.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientGreet: [600]



��'��"��

��'��

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the HELO command.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientHelo: [600]

Description: Time (in seconds) that SMTP-Deliver waits for a server’s response to a MAIL FROM command.

After this time has elapsed, the server times out.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientMailFrom: [600]

Configuration Keys


��'��#��

��'��&��$�

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the QUIT command.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientQuit: [600]

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the RCPT TO command.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientRcptTo: [600]



��'��&��

��'��

Description: Socket timeout value (in seconds) for the SMTP-Deliver process when waiting for a response to the RSET command.

Related Keys: none




Initial Value: 300

Default Value: 600

Example: /*/mta/timeoutClientRset: [600]

Description: Default timeout value (in seconds) the SMTP server uses when reading from a socket.

This is the time that the MTA will wait without success for input/output on this socket before shutting it down

Related Keys: none




Initial Value: 300

Default Value: 0

Example: /*/mta/timeoutServerCommand: [300]

Configuration Keys


��)��

��)��

Description: Timeout value (in seconds) for reads and writes when responding a DATA command.

Related Keys: none




Initial Value: 300

Default Value: 0

Example: /*/mta/timeoutServerData: [300]

Description: Maximum number of seconds that a client must wait for notice of a successful delivery after it has given a message to the MTA.

If InterMail can deliver the message while the client is still connected, it does not need to write the message file to disk or store it in a safe location.

This feature allows InterMail to process messages more quickly by keeping them in memory. However, a long delay period (more than a few seconds) may cause clients to time out, or may be noticeable to end users.

It is advisable that timeoutServerDelivery be no higher than 5.

Related Keys: timeoutServerDeliveryRejection




Initial Value: 5

Default Value: 5

Example: /*/mta/timeoutServerDelivery: [5]



��)��&�4��

��)��

Description: The number of additional seconds the SMTP server should wait for a message to be delivered, after an attempt to write it to disk has failed

Related Keys: timeoutServerDelivery




Initial Value: 5

Default Value: 5

Example: /*/mta/timeoutServerDeliveryRejection: [5]

Description: Path on the file system to the directory for temporary storage on any named server.

tmpDir can be an absolute path or a path relative to the InterMail installation directory.

Related Keys: none




Initial Value: tmp

Default Value: tmp

Example: /*/common/tmpDir: [tmp]

Configuration Keys


��

��/��

Description: Pipe mode when creating trace files for diagnostics.

If zero (0), do not create a named pipe.

If one (1), write to a named pipe, but do not block while waiting for a reader.

If two (2), write to a named pipe, but block if necessary until there is a reader.

The recommended value is 1.

Related Keys: none



Possible Values: 0, 1, or 2

Initial Value: 0

Default Value: 0

Example: /*/common/traceNamedPipeMode: [1]

Description: Level of diagnostic output to the .trace file for any InterMail program. The environment variable IMDIAG can affect this at program startup.

Related Keys: none



Possible Values: any valid trace category/number

Initial Value: null

Default Value: null

Example: /paris/mta/traceOutputLevel: [rme=1,sock=2]



��&��0�

��$��

Description: Adjusts the size of the recorder buffer used for the trace file. A value of 0 will disable the recorder buffer (but still writes to file).

Related Keys:

Servers Affected: All servers.





Example: /*/common/traceRecorderSize: [10240]

Description: Indicates whether the output to a server’s trace file also goes to stderr.

If true for any InterMail application, the output to the trace file also goes to stderr.

Note that, if you launched the program with a -traceToConsole option, the trace also goes to stderr.

But without this guard, setting output trace level could clutter up the screen to the point of making applications unusable, especially if it is /*/common/traceOutputLevel: [default=1], which causes all diagnostic statements to file.

Related Keys: none






Example: /*/common/traceToStderr: [false]

Configuration Keys


��*&��"��

��*

Description: Indicates whether to track and block RCPT TO: harvesters.

Related Keys: Has no effect if /*/mta/verifyRCPTs is false.






Example: /*/mta/trackRcptHarvesters: [false]

Description: Severity of log events reported to the SNMP server for reporting to the monitoring station.

For multiple values, each entry must be on a separate line, between its own set of square brackets.

Related Keys: none



Possible Values: notification, warning, error, urgent, fatal

Initial Value: fatal and urgent

Default Value: null

Example: /*/common/trapMask: [fatal][urgent]



��#��0�

��)

Description: Size (in megabytes) of the queue that each SNMP-enabled server maintains (that is, how many traps can be stored in the queue).

This queue contains the events (traps) sent to the monitoring station periodically.

Related Keys: none




Initial Value: 1024

Default Value: 1024

Example: /*/common/trapQueueSize: [1024]

Description: Used to change the update server DN, which requires rebuilding the Directory database for the Integrated Services Directory. Changing the value causes the update servers to fail on restart until you rebuild their databases.

Related Keys: none



Possible Values: cn=<string>,o=<string>,c=<string>

Initial Value: cn=updatethread,o=software.com,c=us

Default Value: null

Example: /*/common/updateServerDN: [cn=updatethread,o=software.com,c=us]

Configuration Keys


��.��$(��

��'��)��

Description: Determines whether or not to use bound threads.

Related Keys: none

Servers Affected: All servers potentially


Possible Values: true, false


Default Value: /*/common/useBoundThreads: [false]/*/mss/useBoundThreads: [true]/*/imapserv/useBoundThreads: [true]

Example: /*/common/useBoundThreads: [false]

Description: A setting of true allows the writing of the Content-Disposition header for bounced mail.

If true, the Content-Disposition: attachment moves the next sections (that is, not the first section) of multipart mime messages that do not have Content-Type: mime explicitly set.

This is not a default operation because it may make it more difficult for some mailers to resend bounced messages.

Related Keys: none




Initial Value: null


Example: /*/common/useContentDisposition: [false]



��&��

��+��

Description: Indicates whether to use memory mapped reads. If true, then the system uses memory mapping to read files.

Note: This may cause segmentation faults if there are disk errors or other problems when reading the file.

Related Keys: none






Example: /*/common/useMmapReads: [false]

Description: Indicates whether to use memory mapped writes. If true, then the system uses memory mapping to write files.

Related Keys: none






Example: /*/common/useMmapWrites: [false]

Configuration Keys


��!

��.��(��0�

Description: Indicates whether to use MX records when looking up the MX record for a delivery address.

If true, it uses MX records.

If is false, it uses A records.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/mta/UseMx: [true]

Description: Maximum number of directory lookups to perform concurrently.

Related Keys: none




Initial Value: 5

Default Value: 1

Example: /*/mta/validatorBatchSize: [5]



��)��/*

Description: Controls authentication behavior when the Directory server is down. This key has an effect when the relayLocalMustExist, blockLocalNoAcct, verifyRCPTs, or blockPerAccount configuration keys are set:

• When relayLocalMustExist or blockLocalNoAcct are set, the MTA attempts to look up MAIL FROM: addresses in the Directory server.

• When verifyRCPTs or blockPerAccount is set to true and the sender is blocked, the MTA attempts to look up RCPT TO: addresses in the Directory server.

• If the Directory server is down, and the verifyDeferOk configuration key is set to true, the message is not deferred locally. Instead, the MTA responds to the client with a 450 response, rejecting the message. The 450 response means that the client should retry later. Therefore, the client defers the message, and not the server.

• If the verifyDeferOk configuration key is set to false, the message is accepted. If relayLocalMustExist is set to true, and the Directory server is down, the MTA stops enforcing relayLocalMustExist until the Directory server comes back up. This same scenario is true for blockLocalNoAcct, verifyRCPTs, and blockPerAccount

Related Keys: blockLocalNoAcctblockPerAccountrelayLocalMustExistverifyRCPTs






Example: /*/mta/verifyDeferOk: [false]

Configuration Keys


��&��

��'��).

Description: Indicates whether to refuse to accept incoming mail addressed to unknown accounts within a local mail domain. InterMail rejects the message with a standard notice. The sender’s mail client controls responses to that notice (an error message, storage in a dead letter file, and so forth).

Related Keys: none






Example: /*/mta/verifyRcpts: [false]

Description: If true, each time the Configuration server writes a new master configuration database file, the system renames the old one with the following time stamp format:

config.db.YYYYMMDDHHMMSS.

This makes it easy to revert to an earlier configuration database should that be necessary.

Related Keys: none




Initial Value: true

Default Value: true

Example: /*/imconfserv/versionConfigDB: [true]



��

Description: Message ID of the welcome message sent to new accounts.

This is the literal value of the Message-ID header of the new account welcome message, which the immsinit command creates in an administrative mailbox, as Chapter 4 describes.

The Message-ID value of the message immsinit creates is <Welcome>.

Related Keys: none



Possible Values: any valid RFC822 message ID.

Initial Value: <Welcome>

Default Value: null

Example: /*/mss/WelcomeMsgId: [<Welcome>]


3Directory Management Utilities

This chapter describes the command-line utilities that can update InterMail data in the Integrated Services Directory database. These utilities are:

• imdbcontrol

• imbatchextract

• imbatchload

• imintegcheck

• ldapadd

• ldapdelete

• ldapmodify

• ldapmodrdn

• ldapsearch

imdbcontrolThe utility to access mail objects in the Integrated Services Directory is imdbcontrol. To execute imdbcontrol, you must log in as the InterMail user on any InterMail host. Because installation added the location of imdbcontrol to this user’s path, you can execute the utility from any directory.

Note: The imdbcontrol utility operates similar to the UNIX superuser and allows an administrator to override class of service settings and options set through the InterManager interface. For example, if a class of service has a maximum of three aliases for any user, InterManager will strictly enforce this limit. However, by using imdbcontrol, the administrator can override this limit. This allows flexibility when individual accounts contained in a class of service require expanded privileges.



imdbcontrol Syntax The syntax for using imdbcontrol is :

imdbcontrol [-help] [-d] [-e] [-q] [-v][-p <N>] [-] [-h] <option>...

Where:

A command-line option specifies the particular operation a given imdbcontrol instruction performs. The available imdbcontrol options fall into categories of operations involving domains, e-mail accounts, mail delivery, SMTP aliases, class of service, and system logging.

The imdbcontrol command line options are case-insensitive. For example, you can create an account by entering any of the following:

imdbcontrol CreateAccount ...imdbcontrol createaccount ...imdbcontrol CrEaTeAcCoUnT ...

-help Provides complete usage information.

-d Prints debugging information during execution.

-e Causes the program to exit when it encounters errors during batch operations.

-q Suppresses progress reports when the program runs in batch mode.

-v Reports the success or failure of each operation when running in batch mode.

-p Prints progress reports every N lines in batch mode. The default number of lines is 100.

- Processes multiple lines from STDIN and executes them one-by-one, just as if invoking each line with a separate imdbcontrol. (This increases the performance of imdbcontrol by a factor of about 5 in doing batch operations.)

-h Displays usage information for the specified option. For example, entering

imdbcontrol -h CreateAccount

returns usage information (number and type of parameters, etc.) for the CreateAccount option.

<option> Specifies the operation to perform (see table below).

Directory Management Utilities


In addition, you can abbreviate imdbcontrol command line options. For example, you can enter:

imdbcontrol CreateAccount

as:

imdbcontrol ca

Available imdbcontrol OperationsThe following tables provide information on the execution options available with imdbcontrol.

Domain Operations

Account Operations

CreateDomain (cd) Creates a mail domain.

DeleteDomain (dd) Deletes an existing mail domain.

GetDefaultDomain (gdd) Gets the default mail domain.

ListDomains (ld) Shows a list of domains for which InterMail accepts mail.

SetWildcardAccount (sw) Sets the wildcard account for a local domain.

UnsetWildcardAccount (uw) Disables wildcard delivery for a domain.

UpdateDomain (ud) Modifies an existing domain.

CreateAccount (ca) Creates an account.

DeleteAccount (da) Deletes an existing account.

DeleteAccountCos (dac) Deletes a class of service attribute for an account.

GetAccount (ga) List data for an existing account.

GetAccountCos (gac) Displays the per-account class of service attributes and values associated with an account.

GetPassword (gp) Gets the password for an existing account.

ListAccounts (la) Shows a list of all accounts.

ModifyAccount (ma) Modifies an existing account.

ModifyAccountPop (map) Modifies the login name of an existing account.



Mail Delivery Operations

SMTP Alias Operations

ModifyAccountSmtp (mas) Modifies the username of an existing account.

SetAccountCos (sac) Set class of service attributes for an account.

SetAccountQuota (saq) Sets mailbox quotas for an account.

SetAccountStatus (sas) Sets the status of an account (active, locked, etc.)

SetAutoReply (sar) Sets the auto reply mode for an account.

SetAutoReplyHost (sarh) Sets the location of an account’s auto-reply message.

SetPassword (sp) Sets the password for an existing account.

SetProxyHosts (sph) Set proxy hosts for an account.

CreateRemoteForward (crf) Creates a remote forwarding address for an existing InterMail account.

DeleteRemoteForward (drf) Deletes an existing remote forwarding address.

DisableForwarding (df) Disables forwarding for an account.

DisablePOPDelivery (dpd) Disables local delivery (POP and IMAP) for an account.

EnableForwarding (ef) Enables forwarding for an account.

EnablePOPDelivery (epd) Enables local delivery (POP and IMAP) for an InterMail account.

ListAccountForwards (laf) Shows a list of forwarding addresses associated with an InterMail account.

CreateAlias (cl) Creates an SMTP alias for an existing InterMail account.

DeleteAlias (dl) Deletes an existing SMTP alias.

ListAliases (ll) Shows a list of e-mail account aliases.



Class-of-Service Operations

Domain OperationsThis section pertains specifically to using imdbcontrol for domain-related operations, such as creating and deleting local mail domains.

CreateDomain (cd)You can create mail domains with imdbcontrol using the CreateDomain option. Only one parameter is necessary with this option: the name of the new domain to create. By default, new domains are local mail domains, but optional parameters allow you to define the new domain as a non-authoritative (semi-local) or rewrite domain.

Usage

imdbcontrol cd <domain>[ nonauth <relayHost> | rewrite <rewriteValue> ]

Where:

CreateCos (cc) Creates a new class of service.

CreateCosAttribute (cca) Creates a new class of service attribute, which you can then associate with one or more classes of service.

DeleteCos (dc) Deletes an existing class of service.

DeleteCosAttribute (dca) Deletes an existing class of service attribute.

ListCosAttributes (lca) Shows a list of the existing class of service attributes.

ListCosNames (lcn) Shows a list of existing classes of service.

ModifyCosAttribute (mca) Modifies an existing class of service attribute.

SetCosAttribute (sca) Sets the value of a particular attribute for a class of service.

ShowCos (sc) Lists the attributes associated with a class of service.

UnsetCosAttribute (uca) Removes an attribute and its value from a class of service.

<domain> Name of the new domain.

<relayHost> Host to which the system routes mail received for the non-authoritative domain. Only necessary if the new domain is a non-authoritative domain.



Example

imdbcontrol cd software.com

This command creates the local mail domain software.com.

imdbcontrol cd accordance.com rewrite software.com

This command creates the rewrite domain accordance.com. When mail arrives for users in this domain, the system will rewrite the domain name as software.com..

imdbcontrol cd venus.software.com nonauth pluto.software.com

This command creates the non-authoritative domain venus.software.com. When accounts in this domain receive messages, the system will route them to the host pluto.software.com.

Note: You cannot create accounts and alias addresses in a domain until the domain exists. Also, the CreateDomain command will fail if the domain you are creating already exists in the database.

)��)��9:��;

You can delete domains with imdbcontrol by using the DeleteDomain option. Only one parameter is necessary with this option: the name of the domain to delete.

By default, deleting a domain with this option does not remove the domain from the Integrated Services Directory. Instead, it marks the domain as deleted. This allows you to restore the domain later with the UpdateDomain option.

Usage

imdbcontrol dd <domain> [force]

where:

<rewriteValue> Domain name that replaces the domain value when rewriting header addresses. Only necessary if the new domain is a rewrite domain.

<domain> Name of the domain to delete.

force Removes the domain from the Integrated Services Directory permanently.



Example

imdbcontrol dd software.com

This example deletes the domain software.com.

Note: You cannot delete domains if there are any accounts or alias addresses associated with the domain. Before attempting to delete a domain, use the ListAccounts and ListAliases options to check for the existence of accounts, aliases, and forwarding addresses within this domain.

1��)��)��9:��;

You can retrieve the current default domain with imdbcontrol by using the GetDefaultDomain option. This command takes no parameters, and simply outputs the name of the default domain from the configuration database.

Usage

imdbcontrol gdd

Note: The default domain is set with the configuration key /*/mta/defaultDomain:[software.com], where software.com is the the default domain name.

��)��9:��;

You can get a list of mail domains for which InterMail receives e-mail with imdbcontrol by using the ListDomains option. This option takes no parameters, and simply generates a list of domains.

Usage

imdbcontrol ld

Example

This command generates output like the following:

Domain: software.comType: LRelayHost:RewriteDomain:WildcardAcct: [email protected]: venus.software.comType: RRelayHost:RewriteDomain: software.comWildcardAcct:---^^^ # Domains = 2



The previous data includes the following information for a domain:

• Domain name (Domain).

• Type of the domain (Type). The value of this field can be L (local), N (non-authoritative), R (rewrite), or D (deleted).

• The relay host of a non-authoritative domain (RelayHost). This attribute is relevant only for non-authoritative domains.

• The rewrite value of a rewrite domain (RewriteDomain). This value will replace the name of the rewrite domain in recipient addresses. This attribute is relevant only for rewrite domains.

• The address of the wildcard account of the local domain (WildcardAcct). This attribute is relevant only for local domains.

��+��,��9:��;

All mail domains in InterMail can have an optional “wildcard” account associated with them. A wildcard account is simply a normal e-mail account that receives all e-mail sent to unknown addresses within the domain.

For example, if the account [email protected] is a wildcard account for the local mail domain software.com, then any message sent to a non-existent address within software.com will go to [email protected].

Note: Delivery to a wildcard account is, from InterMail’s perspective, a last resort; it occurs only when the destination address of a message does not exist as an account primary address or as an SMTP alias. If the system successfully delivers a message to a normal InterMail account, it will not deliver that same message to a wildcard account as well.

To set a wildcard account for a domain, use imdbcontrol with the SetWildcardAccount option. This option takes two parameters: the domain name, and the primary SMTP address of the existing account that will be the wildcard account.

Usage

imdbcontrol sw <domain> <username>

Where:

Example

imdbcontrol sw mars.software.com unknown

This command sets the e-mail account [email protected] as the wildcard account for the domain mars.software.com.

<domain> Name of the domain.

<username> Address of the e-mail account that will be a wildcard account for this domain.



-��+��,��9:��;

If there is a wildcard account defined for a domain, you can disable wildcard delivery by using imdbcontrol with the UnsetWildcardAccount option. This option takes only one parameter: the domain name.

Usage

imdbcontrol uw <domain>

Where:

Example

imdbcontrol uw mars.software.com

This command removes the wildcard account delivery defined for the domain mars.software.com in the SetWildcardAccount example.

Note: The imdbcontrol UnsetWildcardAccount does not delete the mailbox associated with the wildcard account. In order to delete the mailbox, use the imboxdelete command, described in Chapter 5.

-��)��9:��;

Each domain has an associated type: local, non-authoritative, or rewrite. You can modify the type of an existing domain with imdbcontrol by using the UpdateDomain option. Two parameters are necessary with this option: the name of the domain, and the new type.

You cannot change a local or non-authoritative domain to a rewrite domain directly. To make this change, set the type of a local or non-authoritative domain to deleted, and then set the type to rewrite.

Usage

imdbcontrol ud <domain> { local | nonauth <relayHost> |rewrite <rewriteValue> }

Where:

<domain> Name of the domain to remove wildcard delivery from.

<domain> Name of the existing domain.

<relayHost> Host to which the system routes mail received for the non-authoritative domain. This is only necessary if you are changing the type of the domain to non-authoritative.

<rewriteValue> The domain name that replaces the domain value when rewriting header addresses. Only necessary if changing the type of the domain to rewrite.



Example

imdbcontrol ud accordance.com nonauth mail.accordance.com

This command changes the domain accordance.com to a non-authoritative domain, and sets its relay host value to mail.accordance.com.

imdbcontrol ud accordance.com local

This command changes the accordance.com domain to a local mail domain.

Note: You cannot create accounts and alias addresses in a rewrite domain. If you attempt to change the type of a local or non-authoritative domain to rewrite, and there are accounts associated with the domain, the operation will fail.

Account OperationsThe imdbcontrol operations described in this section are specific to InterMail account-related mail objects.

'��,��9:��;

You can create accounts with imdbcontrol by using the CreateAccount option and specifying several additional pieces of account information. Some of these additional flags are necessary, while others are optional. If you omit any of the optional parameters, then you must omit all subsequent optional parameters.

Usage

imdbcontrol ca <username> <mssHost> <internalId> [<login>] [<password> [-convert] clear|md5|UNIX] [<domain>] [<status>] [cosName]

Where:

<username> Local part of the SMTP address for the account (the part that precedes the “@” symbol in the e-mail address).

<mssHost> Name of the MSS host on which to locate the mailbox for this account.

<internalId> A unique ID shared between the Directory database and the MSS.

<login> POP/IMAP login name.

<password> -convertclear|md5|unix

Password for POP/IMAP access. If specifying a password, also indicate the hashing scheme (or lack thereof). Note that if the -convert option is missing, imdbcontrol does not hash passwords.

<domain> Domain to associate the account with. If you do not specify a domain, it assumes the default domain.



Example

imdbcontrol ca john.doe pluto.software.com 12345 jdoe rosebud clear software.com A Basic

This command creates an account that has the following attributes:

• The SMTP address john.doe in the domain software.com (that is, this account has the e-mail address [email protected]).

• A mailbox on the host pluto.software.com.

• The internal ID number 12345.

• The POP/IMAP login name jdoe.

• The password rosebud.

• The account is active (A).

• The class of service Basic.

)��,��9:��;

You can delete accounts with imdbcontrol by using the DeleteAccount option. Two additional parameters are necessary for this option: the username and domain of the account’s e-mail address.

Usage

imdbcontrol da <username> <domain>

Where:

Example

imdbcontrol da john.doe software.com

This example deletes the account that has the e-mail address [email protected].

<status> Status of the account. The possible values for this parameter are A (active), L (locked), D (deleted), M (maintenance), S (suspended), P (proxy). The default is A (active).

<cosName> Class of service associated with the account. If you do not specify a class of service, it assumes the default class of service.


<domain> Domain associated with the account.



)��,��'��9:��;

You can delete a class of service attribute from an account with imdbcontrol by using the DeleteAccountCos option. Three parameters are necessary with this option: the username portion of the account’s primary SMTP address, the domain associated with the account, and the name of the class of service attribute to delete from the account.

Usage

imdbcontrol dac <username> <domain> <attribute>

Where:

Example

imdbcontrol dac jdoe software.com pref_imap

This example deletes the class of service attribute pref_imap from the account [email protected].

1��,��9:��;

In addition to setting account attributes, imdbcontrol allows you to view all of the attributes of a particular account. The GetAccount option does this, using two additional parameters: the username portion of the account’s primary SMTP address, and the associated domain.

Usage

imdbcontrol ga <username> <domain>

Where:



<attribute> Name of the attribute to delete from the account.





Example

imdbcontrol ga john.doe software.com

This example retrieves all of the mail account information for the account [email protected]. The output from this command looks like:

The preceding data includes the following information for an account:

• Account type (Type). The value of this field can be S (standard) or A (administrative).

• Account status (Status). The value of this field can be A (active), L (locked), D (deleted), M (maintenance), S (suspended), or P (proxy).

• Unique number to identify the account (Internal-ID).

• MSS host that stores the account’s mailbox (Delivery Host).

• Domain of the account’s primary address (Domain Name).

• Username portion of the account’s primary SMTP address (PSMTP Address).

• POP/IMAP address (POP Address).

• Login password (Password).

• Password hashing scheme (Password Hash). The value of this field can be C (clear), U (UNIX), or M (MD5).

• Flag that indicates whether mail forwarding is enabled (Forward). The value of this field can be F (enabled) or N (disabled).

• Flag that indicates whether local delivery is enabled (LocalDelivery). The value of this field can be P (enabled) or N (disabled).

• MSS host that stores the account’s auto-reply message (AutoReply Host).

• Flag that indicates the auto-reply mode (AutoReply Mode). The possible values for this field are N (none), V (vacation), R (reply), or E (echo).

• Class of service associated with the account (COS Name).

Account Info:--- Type: S Status: A Internal-ID: 10671 Delivery Host: pluto.software.com Domain Name: software.com PSMTP Address: john.doe POP Address: jdoe Password: rosebud Password Hash: C Forward: N LocalDelivery: PAutoReply Host: pluto.software.comAutoReply Mode: N COS Name: default---



1��,��'��9:��;

You can retrieve the class of service attribute values for an account with imdbcontrol by using the GetAccountCos option. This command displays the names of all InterMail class of service attributes, their values (if any) at both the class of service and account levels, and the attribute value that currently applies to the account. Two parameters are necessary with this option: the username of the account’s primary SMTP address and the domain associated with the account.

Usage

imdbcontrol gac <username> <domain>

Where:

Example

imdbcontrol gac jdoe software.com

This example retrieves class of service attribute values for the account [email protected]. This command generates output like the following:



Attribute Name Syntax Rule COS Value

Account Value

Result Value

perm_autoreply N L 0 <undef> 0

perm_bypassauthentication N L 0 <undef> 0

perm_echo N L 0 <undef> 0

perm_forwarding N L 0 <undef> 0

perm_localdelivery N L 0 <undef> 0

perm_mtafilter N L 0 <undef> 0

perm_quotabouncenotify N L 0 <undef> 0

perm_quotathreshold N L 0 <undef> 0

perm_vacation N L 0 <undef> 0

pref_bypassauthentication B L 0 <undef> 0

pref_forwarding B G 0 <undef> 0

pref_imap B A 1* <undef> 1



The Result column of the table displayed by the GetAccountCos option contains the value of the attribute that currently applies to the queried account. The precedence rule of the attribute determines this value. For information on attribute precedence rules, see Chapter 4 of the InterMail Kx Operations Guide.

Note: The attributes containing an asterisk (*) indicate that the value shown is not the default value.

pref_intermanager B A 0 <undef> 0

pref_intermanagerssl B A 0 <undef> 0

pref_localdelivery B G 0 <undef> 0

pref_mtafilter B A 0 <undef> 0

pref_numaliases N A 0 <undef> 0

pref_pop B A 1* <undef> 1

pref_popssl B A 0 <undef> 0

pref_quotabouncenotify B L 0 <undef> 0

pref_quotamsgkb N A 0 <undef> 0

pref_quotathreshold N G 0 <undef> 0

pref_quotatotkb N A 0 <undef> 0

pref_quotatotmsgs N A 0 <undef> 0

pref_replymode N A 0 <undef> 0

pref_selfcare B A 0 <undef> 0

pref_selfcaressl B A 0 <undef> 0

pref_smtp B A 1* <undef> 1

pref_smtpauth B A 0 <undef> 0

pref_smtpssl B A 0 <undef> 0

pref_webmail B A 0 <undef> 0

Attribute Name Syntax Rule COS Value

Account Value

Result Value



1��9:��;

You can retrieve account password values with imdbcontrol by using the GetPassword option. Two additional parameters are necessary for this option: the username portion of the account’s primary SMTP address, and the domain associated with the account.

Usage

imdbcontrol gp <username> <domain>

Where:

Example

imdbcontrol gp john.doe software.com

This command gets the password for the account [email protected].

��,��9:��;

While the GetAccount option provides information on a particular account, an additional imdbcontrol option allows you to view this information for all accounts in InterMail, or in a particular domain. The ListAccounts option does this, using only one optional parameter: the domain for the accounts you want information about.

Usage

imdbcontrol la [<domain>]

Where:

Example

imdbcontrol la software.com

This example retrieves mail account information for all accounts in the domain software.com.

imdbcontrol la

This example retrieves mail account information for all accounts in all domains.



<domain> Domain to query for account information. If you do not specify a domain, it retrieves information for all domains.



The format of the information that ListAccounts displays for each account as follows:

The above data includes the following information for an account:

• Primary e-mail address (Addr).

• Login password (Pass).

• Password hashing scheme (Pass-Type). The value of this field can be C (clear), U (UNIX), or M (MD5).

• Account type (Type). The value of this field can be S (standard) or A (administrative).

• Account status (Status). The value of this field can be A (active), L (locked), D (deleted), M (maintenance), S (suspended), or P (proxy).

• MSS host that stores the account’s mailbox (Host).

• Unique number to identify the account (IntID).

• Flag that indicates whether local delivery is enabled (Local Delivery). The value of this field can be P (enabled) or N (disabled).

• Flag that indicates whether mail forwarding is enabled (ForwardFlag). The value of this field can be F (enabled) or N (disabled).

• Flag that indicates the auto-reply mode (AutoReplyMode). The possible values for this field are N (none), V (vacation), R (reply), or E (echo).

• MSS host that stores the account’s auto-reply message (AutoReplyHost).

Note: You cannot delete a domain if the Integrated Services Directory has mail accounts associated with the domain. Before attempting to delete a domain, you should first use the ListAccounts option to check for the existence of mail accounts in this domain, and then delete those accounts if appropriate.

��,��9:��;

You can modify accounts with imdbcontrol by using the ModifyAccount option and specifying several additional pieces of account information. Unlike CreateAccount, the ModifyAccount option requires specifying all account parameters.

Addr: [email protected]: rosebudPass-Type: CType: SStatus: AHost: venusIntID: 6Local Delivery: PForwardFlag: NAutoReplyMode: NAutoReplyHost: pluto



Usage

imdbcontrol ma <username> <mssHost> <internalId> <password> [-convert] <clear|md5|unix> <domain> <status> <cosName>

Where:

Example

imdbcontrol ma john.doe pluto.software.com 12345 rosebud unix -convert software.com A Basic

This command modifies the account created in the CreateAccount example. The only difference is that the hashing scheme of the user’s password has changed from clear to unix.

Note: When using ModifyAccount, it is advisable that you first execute GetAccount to obtain current account information, and then use ModifyAccount to change the account.

You can not modify the username or domain arguments using ModifyAccount. In order to modify the username or domain argument, use imdbcontrol ModifyAccountSmtp.


<mssHost> Name of the MSS host where the mailbox for this account is located.

<internalId> A unique ID for the account shared between the Integrated Services Directory database and the MSS.

<password> [-convert]<clear|md5|unix>

Password for POP/IMAP access. If specifying a password, also indicate the hashing scheme (or lack thereof). Note that if the -convert option is missing, imdbcontrol does not hash passwords.

<domain> Domain associated with the account. If you do not specify a domain, it assumes the default domain.

<status> Status of the account. The possible values for this parameter are A (active), L (locked), D (deleted), M (maintenance), S (suspended), P (proxy).

<cosName> Class of service associated with the account.



��,��9:��;

You can set the login name of an account with imdbcontrol by using the ModifyAccountPop option. Three parameters are necessary for this option: the username portion of the account’s primary SMTP address, the domain associated with the account, and the new login name value.

Usage

imdbcontrol map <username> <domain> <popLogin>

Where:

Example

imdbcontrol map john.doe software.com johndoe

This example changes the POP/IMAP login name of the account [email protected] to johndoe.

��,��9:��;

You can change the primary e-mail address of an account with imdbcontrol by using the ModifyAccountSmtp option. Four parameters are necessary for this option: the current username of the account, the domain associated with the account, the new username value, and the new domain.

Usage

imdbcontrol mas <username> <domain> <newUsername><newDomain>

Where:



<popLogin> New POP/IMAP login name value.



<newUsername> New username value for the account.

<newDomain> New domain for the account.



Example

imdbcontrol mas john.doe software.com jdoe sales.software.com

This example changes the primary e-mail address of an account from [email protected] to [email protected].

��,��'��9:��;

You can define the value of a class of service attribute for an account with imdbcontrol by using the SetAccountCos option. Four parameters are necessary with this option: the username portion of the account’s primary SMTP address, the domain associated with the account, the name of the class of service attribute, and the value of the attribute. You may repeat the attribute and value parameters to allow for setting multiple attributes in a single operation.

Usage

imdbcontrol sac <username> <domain> <attribute> <value> ...

Where:

Example

imdbcontrol sac jdoe software.com pref_imap 1

This example sets values for the class of service attribute pref_imap for the account [email protected]. The value 1 indicates that the command is setting this Boolean attribute to true.



<attribute> Name of the attribute. More than one attribute can appear in a single execution, each with its own value.

<value> Value of the attribute.



��,��#��9:��7;

You can set quota values at the account level with imdbcontrol by using the SetAccountQuota option. This command takes up to six parameters: the username portion of the account’s primary SMTP address, the domain associated with this address, and the four available quota options. When setting values for the maximum number of messages, maximum message size, and quota warning threshold, you must specify a keyword (maxMsgs, maxMsgBytes, and quotaThreshold, respectively) with the value.

Usage

imdbcontrol saq <username> <domain> <mboxMaxBytes> [maxMsgs=<mboxMaxMsgs>] [maxMsgBytes=<mboxMaxMsgBytes>] [quotaThreshold=<percentage>]

Where:

Example

imdbcontrol saq john.doe software.com 10000000 maxMsgs=2000 maxMsgBytes=3000000 quotaThreshold=90

This command sets values for all of the available quota options for the account [email protected]. These values set the following behaviors for the account:

• The account’s mailbox can contain no more than 10 MB (10,000,000 bytes) of mail.

• The account’s mailbox can contain no more than 2,000 messages.

• The account will accept only messages of less than 3 MB (3,000,000 bytes) .

• When the account’s mailbox reaches 90% of capacity (that is, when the mailbox contains 9 MB of mail, in this case) the system sends the user a warning message.

Note: The default value for all account quotas is 0, which specifies that there are no limits on the account.



<mboxMaxBytes> Maximum size (in bytes) of the account’s mailbox.

<mboxMaxMsgs> Maximum number of messages allowed in the account’s mailbox.

<mboxMaxMsgBytes> Largest message (in bytes) that the account can receive.

<percentage> Quota warning threshold (as a percentage of the mboxMaxBytes limit).



��,��9:��;

To set the status of an account, use imdbcontrol with the SetAccountStatus option. This command takes three parameters: the username portion of the account’s primary SMTP address, the domain associated with this address, and a flag that indicates the account’s new status.

Usage

imdbcontrol sas <username> <domain> <status>

Where:

Example

imdbcontrol sas john.doe software.com S

This example changes the status of the account [email protected] to suspended (S).

��,��&��9:��;

You can enable auto-reply for an account with imdbcontrol by using the SetAutoReply option. Three parameters are necessary with this option: the username portion of the account’s primary SMTP address, the domain associated with this address, and the mode of auto-reply.

Usage

imdbcontrol sar <username> <domain> <autoReplyMode>

Where:



<status> New status of the account. The possible values for this parameter are A (active), L (locked), D (deleted), M (maintenance), S (suspended), P (proxy).



<autoReplyMode> Mode of auto-reply the account uses. The possible values for this parameter are N (none), V (vacation), R (reply), E (echo).



Example

imdbcontrol sar john.doe software.com V

This example enables an auto-reply for the account [email protected], using the vacation mode.

Note: The Integrated Services Directory does not store the auto-reply message associated with an account. Therefore, imdbcontrol cannot set the auto-reply message. The hosts that contain account mailboxes (that is, the hosts that run the InterMail Message Store Server) store auto-reply messages as text files. Use the SetAutoReplyHost option with imdbcontrol to set the location of an account’s auto-reply message.

��,��&��"��9:��(;

All InterMail accounts include an optional auto-reply feature. The status of this feature (enabled or disabled) and its mode of operation (vacation, reply, and echo) are in the Integrated Services Directory. However, the actual text of an account’s auto-reply message is on the file system of a host that runs the InterMail Message Store Server (MSS). Setting up the auto-reply feature for an account therefore includes specifying the MSS host on which the account’s auto-reply message is stored.

You can set the location of an auto-reply message for an account with imdbcontrol by using the SetAutoReplyHost option. Three parameters are necessary with this option: the username portion of the account’s primary SMTP address, the domain associated with this address, and the hostname of the system storing the auto-reply message.

Usage

imdbcontrol sarh <username> <domain> <autoReplyHost>

Where:

Example

imdbcontrol sarh john.doe software.com venus.software.com

This command sets the host venus.software.com as the location of the auto-reply message for the account [email protected].

Note: The name of the file that contains an account’s auto-reply message is in the MSS database. To specify the auto-reply file for an account, use the imreplyctrl command described in Chapter 5.



<autoReplyHost> Host name of the system storing the account’s auto-reply message.



��9:��;

You can set account password values with imdbcontrol by using the SetPassword option. Four parameters are necessary for this option: the username portion of the account’s primary SMTP address, the domain associated with the account, the new password, and the hashing scheme for the password.

Usage

imdbcontrol sp <username> <domain> <password> clear|md5|UNIX [-convert]

Where:

Example

imdbcontrol sp john.doe software.com $ecret clear

This example changes the password for the account [email protected] to $ecret, stored in clear text format.

��!"��9:��(;

You can set a proxy host for mail access (POP/IMAP) or mail delivery (SMTP) using imdbcontrol with the SetProxyHosts option. This option is useful when transitioning a legacy mail system to an InterMail system, thus preventing service interruption. Mail can be accessed or delivered to the legacy system, while InterMail system integration is performed.

Usage

imdbcontrol sph <username> <domain> <popHost> <smtpHost>

Where:



<password> New password value for the account.

clear|md5|UNIX Hashing algorithm to store the password in the database.

[-convert] Optional flag that specifies that imdbcontrol should hash the password according to the given hashing scheme.





Mail Delivery Operations

'��&��9:��;

To forward mail from an InterMail account to an account in a remote mail domain, create a forwarding address with imdbcontrol by using the CreateRemoteForward option. Three parameters are necessary with the CreateRemoteForward option: the username portion of the account’s primary SMTP address, the domain associated with this address, and the full address (username + “@” + domain) to which to forward mail.

Usage

imdbcontrol crf <username> <domain><forwardTo>

Where:

Example

imdbcontrol crf john.doe software.com [email protected]

This example creates the forwarding address [email protected] for the account [email protected].

Note: Even if you have created a forwarding address for an account, the system will not forward mail from this account unless you have specifically enabled forwarding delivery for the account.

)��&��9:��;

You can delete forwarding addresses from an account with imdbcontrol by using the DeleteRemoteForward option. Three parameters are necessary with this option: the username portion of the account’s primary SMTP address, the domain associated with this address, and the full forwarding address (username + “@” + domain) to delete.

<popHost> The POP/IMAP host from which this account will access mail.

<smtpHost> The SMTP host where mail for this account will be delivered.


<domain> Domain associated with the account’s primary SMTP address. Optional only if there is a default domain. If omitted, it assumes the default domain.

<forwardTo> The complete remote address to define as a forwarding address.



Usage

imdbcontrol drf <username> <domain> <forwardTo>

Where:

Example

imdbcontrol drf john.doe software.com [email protected]

This example deletes the remote forwarding address [email protected] that the CreateRemoteForward example created for the local account [email protected].

Note: Deleting an account’s last forwarding address automatically enables local (POP) delivery for the account, if previously disabled.

)��9:��;

You can disable forwarding for an account with imdbcontrol by using the DisableForwarding option. Disabling forwarding delivery this way allows you to stop mail forwarding from an account without permanently deleting all forwarding addresses associated with the account. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address, and the domain associated with this address.

Note: Executing this option automatically enables local (POP) delivery if previously disabled.

Usage

imdbcontrol df <username> <domain>

Where:


<domain> Domain associated with the account’s primary SMTP address

<forwardTo> Complete remote forwarding address to delete.





Example

imdbcontrol df john.doe software.com

This command disables forwarding delivery for the account [email protected]. Once disabled, the system will not forward messages addressed to this account, regardless of whether there are any local or remote forwarding addresses defined for this account.

)��/�)��9:��;

You can disable local delivery for an account with imdbcontrol by using the DisablePOPDelivery option. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address, and the domain associated with this address.

Usage

imdbcontrol dpd <username> <domain>

Where:

Example

imdbcontrol dpd john.doe software.com

This command disables local delivery for the account [email protected]. When you disable local delivery for an account, messages sent to that account no longer go to the account’s mailbox.

Note: An account that does not use local delivery must use mail forwarding.





��9:��;

To enable mail forwarding for an account, use imdbcontrol with the EnableForwarding option. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address, and the domain associated with this address.

Usage

imdbcontrol ef <username> <domain>

Where:

Example

imdbcontrol ef john.doe software.com

This command enables forwarding delivery for the account [email protected]. With this delivery method enabled, the system will forward all messages sent to [email protected] to the forwarding addresses defined for this account.

��/�)��9:��;

The most common method of mail delivery for InterMail accounts is local delivery. This method of delivery stores all messages sent to the account in a mailbox, from which a POP3 or IMAP4 mail client can access them.

You can enable local delivery for an account with imdbcontrol by using the EnablePOPDelivery option. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address, and the domain associated with this address.

Usage

imdbcontrol epd <username> <domain>

Where:







Example

imdbcontrol epd john.doe software.com

This command enables local delivery for the account [email protected]. With this delivery method enabled, all messages sent to [email protected] will go to the account’s mailbox, from which the POP3 Server or IMAP Server can retrieve them.

��,��9:��;

To get a list of the forwarding addresses that are associated with an e-mail account, use imdbcontrol with the ListAccountForwards option. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address, and the domain associated with this address.

Usage

imdbcontrol laf <username> <domain>

Where:

Example

imdbcontrol laf john.doe software.com

This command lists the local and remote forwarding addresses associated with the account [email protected]. Output from this command includes only the relevant forwarding addresses, one per line. For example:

[email protected]@Wossamotta-U.edu

SMTP Alias Operations

'��,��9:��;

You can create alias addresses for an account with imdbcontrol by using the CreateAlias option. Two parameters are necessary with this option: the username portion of the account’s primary SMTP address and the username portion of the alias address that you are adding. If there is no default domain set, you must also specify the domains associated with these addresses. It is common to create aliases like this to let users receive mail sent to multiple addresses.





Usage

imdbcontrol cl <username> <aliasUsername> [<domain>] [<aliasDomain>]

Where:

Example

imdbcontrol cl john.doe sales software.com software.com

This command adds the alias address [email protected] to the account whose primary SMTP address is [email protected].

)��,��9:��;

You can delete alias addresses with imdbcontrol by using the DeleteAlias option. Two parameters are necessary with the DeleteAlias option: the username portion of the alias address, and the domain associated with this alias.

Usage

imdbcontrol dl <username> <domain>

Where:

Example

imdbcontrol dl sales software.com

This command deletes the alias address [email protected] created in the CreateAlias example.


<aliasUsername> Local portion of the new alias address.

<domain> Domain associated with the account’s primary SMTP address. Optional only if there is a default domain.

<aliasDomain> Domain to associate with the new alias address. If omitted, it assumes the default domain.

<username> Local portion of the alias address to delete.

<domain> Domain of the alias address.



��,��9:��;

In addition to information about a particular account, you can use imdbcontrol to query the Integrated Services Directory for a list of all alias addresses in the system, or the aliases associated with a particular account. The ListAliases option does this, using two optional parameters: the username portion of the account’s primary SMTP address, and the domain associated with this address. (You must either specify both or neither of these arguments.)

Usage

imdbcontrol ll [<username> <domain>]

Where:

Example

imdbcontrol ll john.doe software.com

This command returns a list of SMTP aliases associated with the account [email protected].

imdbcontrol ll

This example retrieves information for all alias addresses in all domains.

Note: You cannot delete a domain if the Integrated Services Directory has one or more alias addresses associated with the domain. Before attempting to delete a domain, you should first use the ListAliases option to check for the existence of alias addresses in this domain, and then delete those aliases if appropriate.

Class-of-Service OperationsThe imdbcontrol operations described in this section relate to InterMail classes of service.

'��'��9:��;

You can create new classes of service with imdbcontrol by using the CreateCos option. Only one parameter is necessary with this option: the name of the new class of service to create.


<domain> Domain associated with the account’s primary SMTP address.



Usage

imdbcontrol cc <classOfService>

Where:

Example

imdbcontrol cc Premium

This example creates a new class of service named “Premium”.

'��'��,��9:��;

You can create new class of service attributes with imdbcontrol by using the CreateCosAttribute option. Three parameters are necessary with this option: the name of the new attribute to create, its precedence rule, and its type.

Usage

imdbcontrol cca <attribute> <rule> <type>

Where:

Example

imdbcontrol cca pref_pager L B

This example creates a new class of service attribute named pref_pager. This attribute is Boolean (B), and the precedence rule specifies that the lower (L) of the class of service and per-account values should be the value for an account.

<classOfService> Name of the new class of service.

<attribute> Name of the new class of service attribute to create.

<rule> Precedence rule that defines whether the value of the attribute for an account is defined in the account or its class of service. The possible values for this parameter are:

C (use class of service value)A (use account value)L (use the lesser of the class of service and account values)G (use the greater of the class of service and account values)

In all cases, if the attribute is defined for either the class of service or the account, but not both, use the value of the one instance.

<type> Type of the new attribute. The possible values for this parameter are S (string), N (numeric), and B (Boolean).



)��'��9:��;

You can delete classes of service with imdbcontrol by using the DeleteCos option. Only one parameter is necessary with this option: the name of the class of service to delete.

Usage

imdbcontrol dc <classOfService>

Where:

Example

imdbcontrol dc Premium++

This command deletes the class of service named “Premium++”.

)��'��,��9:��;

You can delete existing class of service attributes with imdbcontrol by using the DeleteCosAttribute option. Only one parameter is necessary with this option: the name of the attribute to delete.

Usage

imdbcontrol dca <attribute>

Where:

Example

imdbcontrol dca pref_pager

This example deletes the class of service attribute named pref_pager.

��'��,��9:��;

You can list information on all available class of service attributes in the system with imdbcontrol by using the ListCosAttributes option. This option takes no parameters, and simply outputs the following information for each class of service attribute:

• Name of the attribute (i.e. pref_quotatotmsgs)

• Precedence rule, which can be one of the following values:

C (class of service value overrides per-account values)A (per-account values override class of service value)L (uses the lesser of the class of service and per-account values)G (uses the greater of the class of service and per-account values)

<classOfService> Name of the class of service to delete.

<attribute> Name of the class of service attribute to delete.



• Data type, which can be one of the following values:

B (Boolean)N (numeric)S (string)

Usage

imdbcontrol lca

Example

This option generates output like the following:

Name: pref_quotatotmsgs; Rule: A; Syntax: NName: perm_vacation; Rule: L; Syntax: NName: pref_intermanager; Rule: A; Syntax: BName: pref_quotamsgkb; Rule: A; Syntax: N...

��'��9:��;

You can display the list of existing classes of service with imdbcontrol by using the ListCosNames option. This option takes no parameters, and simply produces a list of classes of service.

Usage

imdbcontrol lcn

��'��,��9:��;

You can modify the precedence rule associated with a class of service attribute with imdbcontrol by using the ModifyCosAttribute option. Two parameters are necessary with this option: the name of the new attribute to modify, and the new precedence rule value.

Usage

imdbcontrol mca <attribute> <rule>

Where:

<attribute> Name of the class of service attribute to modify.

<rule> Precedence rule that defines whether the value of the attribute for an account is defined in the account or its class of service. The possible values for this parameter are:

C (use class of service value)A (use account value)L (use the lesser of the class of service and account values)G (use the greater of the class of service and account values)

In all cases, if the attribute is defined for either the class of service or the account, but not both, use the value of the one instance.



Example

imdbcontrol mca pref_pager A

This example changes the precedence rule for the attribute pref_pager to use the per-account (A) value of the attribute.

��'��,��9:��;

You can define the value of an attribute for a class of service with imdbcontrol by using the SetCosAttribute option. Three parameters are necessary with this option: the name of the class of service, the name of the attribute, and the value of the attribute.

Usage

imdbcontrol sca <classOfService> <attribute> <value>

where:

Example

imdbcontrol sca Basic pref_popSSL 1

This example sets the attribute pref_popSSL for a class of service named “Basic.” The given value of 1 indicates that the command is setting this Boolean attribute to on.

�(��'��9:��;

You can display the attributes associated with a class of service, as well as their values, with imdbcontrol by using the ShowCos option. Only one parameter is necessary with this option: the name of the class of service you want to examine.

Usage

imdbcontrol sc <classOfService>

Where:

Example

imdbcontrol sc Premium

This command lists the attributes associated with the class of service named “Premium++”. This command generates output like the following:

pref_pop:1pref_smtpssl:1

<classOfService> Name of the class of service for which to define the attribute.

<attribute> Name of the attribute.

<value> Value of the attribute.

<classOfService> Name of the class of service to query.



-��'��,��9:��;

You can delete an attribute from a class of service with imdbcontrol by using the SetCosAttribute option. When this option executes, it deletes the existing value of the attribute for the given class of service, which is no longer associated with that attribute. Two parameters are necessary with this option: the name of the class of service and the name of the attribute.

Usage

imdbcontrol uca <classOfService> <attribute>

Where:

Example

imdbcontrol uca Basic pref_popSSL

This example disassociates the attribute pref_popSSL with a class of service named “Basic.” This deletes the value for this attribute in the Basic class of service.

imbatchextractThe imbatchextract utility is used when existing InterMail customers already have mail account information stored in the Integrated Services Directory. Where InterMail account data already exists, it is possible to extract this information and use it to populate InterManager’s data tables.

Note: The process of synchronizing account and InterManager information involves the input of extracted information using imbatchload. Please see Section imbatchload for more information on imbatchload.

imbatchextract SyntaxThe imbatchextract utility creates a text file of user information drawn from InterMail’s database tables. This information is presented in a format that can be read by the imbatchload data loading utility.

Note: Some editing of the output of imbatchextract is required in order for imbatchload to accept it. The details denoted by < > in the file must be filled in.

<classOfService> Name of the class of service for which to remove the attribute.

<attribute> Name of the attribute.



The syntax for imbatchextract is:

imbatchextract [-v] [-h] -f <output file name> [-o <object type>][-p <page size>][-d <domain name>][-s <starting username part of the primary SMTP address>][-t <”till” username part of the primary SMTP address>]

Where:

Note: The arguments –d, -p, -s and –t are allowed only when the object type is account.

-v Verbose. Does nothing.

-h Prints the usage statement.

-f Specifies the name of the output file.

-o Specifies the object type to be dumped. Valid object types are accounts and classes of service. The parameter used by –o should be a valid account or class of service name. For example, -o premium, would produce records for the premium class of service. If no object type is specified, then information about all accounts and classes of service is listed in the output file.

-d Specifies the domain name for accounts that are to be listed. For example, -d acmecola.com would list accounts belonging to Acme Cola’s domain.

-p Specifies the page size to be used while extracting account information. Too small a page size makes the extraction process too slow. Too large a page size requires greater amounts of memory. The default page size is 1000.

-s Specifies the starting point for the username part of the primary SMTP address. The indicated parameter is excluded. For example, -s g means that the data dump will begin with accounts whose primary SMTP address begins with the letter h.

-t Specifies the ending point for the username part of the primary SMTP address. The indicated parameter is excluded. For example, -t l means that the data dump will end with accounts whose primary SMTP address begins with the letter k.



Creating a Targeted User Batch FileUsing the syntax and arguments described in the previous section, it is possible to create user batch files that are very narrowly defined.

For example, the following syntax would create an output file named acme_h-k for all accounts whose primary SMTP addresses begin with the letter h through the letter k.

imbatchextract –f acme_h-k –s g –t l

This might be useful if you wanted to create small organizational units for a company in order to reduce the workload on a single organizational unit administrator. You might, for example, want to divide an organizational unit for a company into three smaller organizational units that are simply based on an alphabetical range of SMTP addresses—a-e, f-l, and m-z. The ability to specify a range of accounts for your imbatchextract output file makes it easy to batch load a narrow range of accounts into a specific organization or organizational unit.

imbatchload The imbatchload utility takes the contents of the specified input file(s) and imports the data into InterManager. The input format is a modified form of LDIF. This utility can be used to add a large number of InterManager accounts, which may then be managed in groups in a delegated administration hierarchy. Entries are created in the directory database only if they do not already exist.

The imbatchload utility is most commonly used to import files created by imbatchextract when there is information in mail account data tables, but not in InterManager data tables. imbatchload can also be used to recreate the directory database in the event of a disaster, using the information in the sitestartup.batch and sitestartup/install files in $INTERMAIL/lib.

imbatchload SyntaxThe syntax for using imbatchload is:

imbatchload [options] <files- | ->

Where:

When executed, imbatchload takes the contents of the specified input file(s) and imports the data into the InterManager data hierarchy.

[options] Describes a processing option described below.

<file> Specifies the name of the file containing data entries to be added to InterManager. Multiple input files may be specified in a single execution.



The options for imbatchload are:

imbatchload Input File The general form of the imbatchload input file is a sequence of records separated by blank lines. The first line of each record specifies the record type.

There are seven record types:

-help Gives you the help for the command

-bind Provide a bind name

-bindpw Provide a bind password

-host Provide an InterManager host name

-Error <Abort|Continue> Select an error handling method

-noimgr Run without InterManager installed

Record Description

Context Describes a parent context for the records that follow

IM_Type Describes an entry (which may be a domain, a class of service, the provider organization, another organization, an organizational unit, or a person)

COS_Assign Assigns a class of service to an organization

Option Describes a processing option

Defaults Describes the default attributes for a class

ChangeType Describes the processing mode for the following records

Comment An arbitrary comment line in the file (these are ignored)



Ordering of Entries in the Input File

The input file describes structure and is context sensitive, therefore the ordering of entries within the file is significant.

When the user batch file is created, the record types must be in the following order:

context:provider: <provider name>

The provider’s context record must come first. This creates the parent context for the service provider, and becomes the parent record for all subsequent entries. Any customer organizations that follow will be part of the service provider’s site.

IM_Type: Domain

This record identifies the service provider’s domain and follows the context record for the provider.

IM_Type: MailCOS

This record type creates a class of service that can (optionally) be assigned to each of the provider’s customer organizations. As many MailCOS records as required can be created within the provider’s organizational context.

COS_Assign: <class of service name>

This record type is used to assign a class of service to a specific organization. The COS_Assign record always applies to the last organization created. In other words, if a COS_Assign record is created beneath the record that creates the organization for Acme Cola, then Acme Cola’s own organization administrator has the ability to place Acme Cola users in that class of service.

IM_Type: Org

This record creates a top-level organization within the site. The record automatically creates a context entry for this organization. Any entries for organizational units or users that fall within this context will be part of this organization.

IM_Type: OrgUnit

This record is used to create organizational units within top-level organizations. To create two or more organizational units within a single top-level organization, you must first create another IM_Type:Org record for that organization to reset the context. The second IM_Type:OrgUnit record would then be placed beneath the second IM_Type:Org record.

If you were to create two organizational units for the same top-level organization without first resetting the context with a new IM_Type:Org record, the second organizational unit would be created nested inside the first. In other words, the top-level organization would be the parent, the first organizational unit would be its child, and the second organizational unit would be the child of the first organizational unit.

IM_Type: Person

This is the record type that creates entries for user accounts. Person records will be loaded into the organization or organizational unit that was last stipulated in the file.



Summary of Record Sequencing

To summarize, the overall structure for the batch loading input file is as follows:

ContextDomain (optional unless Organization is being created)Organization

organization attributesOrgUnit <organizational unit attributes>[optionally repeat OrgUnit to get child organizational units]Person

<person attributes>

Input File Record TypesThe record types referenced in the preceding sections are defined in the sections that follow. Examples of each record type are provided.

Entry Records

Each entry is specified as a list of attributes. Each attribute is entered in pure LDIF manner, as in:

<attr name>: <attr value>

or

<attr name>:: <attr value encoded BASE64>

Note: Attribute values may be folded onto extension lines per the LDIF format definition.

The macrostructure of each entry is as follows:

IM_Type: <intermanagerClass> [<entryNumber>] <attributes>

Where:

<entryNumber> An optional number used strictly to assist in identifying errors in the file.

Note: This number is defined as 32bit unsigned integer.

<intermanagerClass> Any one of the following: Domain, Provider, Org, OrgUnit, Person, MailCOS, MailGroup, MailTemplate.

Note: Domain, Org, and OrgUnit are structural entries that establish a new parent context for the entry records that follow.

<attributes> A list of attributes for the entry.



Required Attributes

Each entry record has a set of required attributes. Other attributes may be added, provided they’re allowed by the InterManager classes. Required attributes for each entry type are indicated below.

Domain:

domain: <domain name>domainType: <type = LOCAL|REWRITE|NON-AUTH>

Provider:

provider: <provider name>domain: <domain name>

Organization:

domain: <organization’s domain name>o: <organization name>

Organizational unit:

ou: <organizational unit name>

Person:

uid: <smtpAddress>mailCOS: <class of service>emailPassword: <password>passwordType: <type = CLEAR|MD5|UNIX> CLEAR is optionalmessageStoreHost: <hostname>mailboxStatus: <status = ACTIVE|SUSPENDED|MAINTENANCE|LOCKED|PROXY>

MailCOS:

mailCOS: <class of service>serviceDef: <multivalue>

Context Records

This record establishes the entry to use as the parent for the entry records that follow. Once context established, it remains in effect until a new context established (either by a new Context record or by an entry record for a new structural entry).

The format of a context record is a Context tag followed by a list of structural entry names, ordered from the most significant to the least.

Example

The entry below indicates that all records that follow pertain to Software.com’s Engineering organizational unit.

Context:o: Software.com, Inc.ou: Engineering



Class-of-Service Assignment Records

This record is used to assign a class of service to an organization. The class of service and the organization must exist. The current parent context must be the organization that will have the class of service assigned. The COS_Assign record(s) must either follow the organization’s create (IM_Type) record, or there must be a Context record preceding the COS_Assign(s).

The COS_Assign must contain at least the maxusers attribute. It may also have the following attributes: messagestorehost, alternatehost, and description.

Example

The entry below sets Software.com’s organization as context. As a result, the entry that follows is understood to assign the SiteAdmin class of service to the Software.com organization.

Engineering organizational unit.

Context:o: Software.com, Inc.

COS_Assign: SiteAdminmaxusers: 10messagestorehost: venus.software.com alternatehost: pluto.software.com

Option Records

An option record invokes a processing option. The option remains in effect until explicitly changed.

The following options set error handling:

Option Description

ErrorAbort Terminate import on error

ErrorContinue Continue import on error

ErrorDefaults Restore error handle to defaults (or command line)

ErrorOnExistAccount Report error if the account exists

ErrorOnExistDomain Report error if the domain exists

ErrorOnExist<entry> Report error if specified LDAP entry exists

ErrorOnNonExistAccount Report error if account doesn’t exist

ErrorOnNonExistDomain Report error if domain doesn’t exist

ErrorOnNonExist<entry> Report error if specified LDAP entry does not exist

IgnoreExistAccount Don’t report existing account



Note that the <entry> referenced above can be an organization, organizational unit, or person. The defaults for the various entries are as follows:

• organization (IgnoreExistOrganization, IgnoreExistDomain)

• organizational unit (IgnoreExistOrgUnit)

• person (ErrorOnExistPerson, IgnoreExistAccount)

Note: The ErrorAbort and ErrorContinue options apply to all errors, not just errors indicating that an item does or does not exist. For this reason, ErrorContinue should be used with caution.

Default Records

A default record is used to specify the default values for the attributes of an InterManager class. It is specified in the same form as an entry record, except no name attribute is required.

A default setting remains in effect until another default record of the same class is specified.

Example

The entry below sets the default attributes so that each person record that follows is automatically associated with the MegaBasic class of service, assigned a password protected by MD5 encryption, and given a locked mailbox.

Default: PersonmailCOS: MegaBasic passwordType: MD5mailboxStatus: locked

Change Records

The ChangeType record alters the processing of entry records. Available change types are:

IgnoreExistDomain Don’t report existing domain

IgnoreExist<entry> Don’t report existing LDAP entry

IgnoreNonExistAccount Don’t report non-existing account

IgnoreNonExistDomain Don’t report non-existing domain

IgnoreNonExist<entry> Don’t report non-existing LDAP entry

Type Description

add Add the record (the default)

Option Description



Example

The entry below modifies the person record for John Doe: adding zip code information, changing his billing ID, and deleting his Telex number.

ChangeType: Modify

IM_Type: Personuid: [email protected] add: postalCodepostalCode: 98004-modify: billingIdbillingId: 0-delete: telexNumber-

Comment Record

A comment record is used to annotate a file for human reading. Comments are denoted by a pound sign (#) in the first column. Comments are ignored by the batch loading utility.

imintegcheckThe imintegcheck utility checks the integrity of the data in the InterMail Directory database and reports invalid relationships among data objects. Directory data objects are related to each other in a tree structure. imintegcheck checks this tree structure for completeness. For example, it verifies that every organization has a ‘mail data’ subtree.

In addition, some directory objects have references to other directory objects. imintegcheck verifies that these object references are correct. For example, it makes sure that a reference in a mail group object to a mail policy object actually does point to an existing mail policy object. If this is not the case, it reports it.

imintegcheck also checks attributes within data objects to ensure that their values are valid. For example, the description attribute for adminGroup objects must have one of the following values: ‘org admins’, ‘csr admins’, or ‘site admins’. If an adminGroup object does not have one of these values, imintegcheck will flag it.

delete Delete the specified entry records. Note that this should be specified after the organization, organizational unit context.

newParent The following records will be moved to a new parent. Note this also should be specified after the organization, organizational unit context.

modify Modify an existing record.

Type Description



imintegcheck Syntaximintegcheck [-help] [-h <host>] [-p <port>] [-b <search Base>] [<option>]

Where:

Note: All operations can specified with abbreviations using the first initials of the words in the argument (for example, ‘lea' for ListExtraAccounts).

imintegcheck OperationsThe imintegcheck utility can be used for a variety of directory checking operations, as shown in the following list.

Note: The <searchBaseDN> argument for imintegcheck specifies the DIT node below which the mail group objects should be checked.

• imintegcheck ListMailGroupsWithInvalidMailPolicy (lmgwimp)<searchBaseDN>—lists the DNs of the mailGroup objects for which the mailPolicy attribute has an invalid value. The mailPolicy attribute is reported as invalid when the value DN points to a non-existing mailPolicy object.

• imintegcheck ListAdminGroupsWithInvalidMember (lagwim)<searchBaseDN>—lists the DNs of the adminGroup objects for which the member attribute has invalid values. The member attribute is reported as invalid when the value DN points to a non-existing mailUser (person) object.

• imintegcheck ListOrganizationsWithNoMailDataSubtree (lownmds)<searchBaseDN>—lists DNs of the organizations which do not have ’mail data’ subtree.

• imintegcheck ListProviderOrganizationsWithNoMailPoliciesSubtree (lpownmps)<searchBaseDN>—lists DNs of the provider organizations which do not have ’mail policies’ subtree.

-help Provides complete usage information

-h Specifies the LDAP Server host name

-p Specifies the LDAP Server port

-b Specifies the DN (distinguished name)of the Directory tree node below which the check is to be performed

<option> One of the operations described below, either fully specified or abbreviated. If no options are specified, all checks will be performed.



• imintegcheck ListOrganizationsWithNoOrgAdminGroup (lownoag)<searchBaseDN>—lists DNs of the organizations which do not have an organization admins group entry.

• imintegcheck ListProviderOrganizationsWithMissingAdminGroups (lpowmag)<searchBaseDN>—lists DNs of the provider organizations which do not have an admin group entry either for ’site admin,’ ’csr admin,’ or ’org admin.’

• imintegcheck ListPersonsWithInconsistentMailAttributes (lpwima)<searchBaseDN>—lists DNs of the LDAP person entries for which the 'mail' attribute value does not appear in the ‘smtpAddress’ attribute.

• imintegcheck ListOrganizationsWithInvalidAllowedDomains (lowiad)<searchBaseDN>—lists DNs of the organizations for which the values of the ‘allowedDomains’ attribute do not exist as ‘mailDomain’ entries in the directory.

• imintegcheck ListMailGroupsWithInvalidNumUsers (lmgwinu) <searchBaseDN> – lists the DNs of the mailGroup objects for which ‘numUsers’ value is greater than ‘maxUsers’ value.

• imintegcheck ListAdminGroupsWithInvalidDescription (lagwid) <searchBaseDN> – lists the DNs of the adminGroup objects for which the description attribute does not have one of the following values: ‘org admins’, ‘ou admins’, ‘csr admins’, ‘site admins’

ldapaddThe ldapadd command allows you to add new entries to the Directory database. It is an LDAP utility originally developed by the University of Michigan and adapted by Software.com. ldapadd is a special instance of ldapmodify, which is defined in Section 15.23.

Syntax

The syntax is the same as the syntax for ldapmodify, except that the –a option is internally set to add new entries, and therefore not used explicitly.

ldapadd [-b] [-c] [-r] [-n] [-v] [-d level] [-D binddn] [-w passwd][-h host] [-p port] [-f file]



ldapdeleteThe ldapdelete command allows you to delete one or more entries from the Directory database. It is an LDAP utility originally developed by the University of Michigan and adapted by Software.com.

Syntax

ldapdelete [-n] [-v] [-c] [-d level] [-f file] [-D binddn][-w passwd] [-h host] [-p port] [dn]

Where:

Example

ldapdelete "cn=Delete Me, o=Software.com, c=US"

will delete the entry named with common name Delete Me directly below the Software.com organizational entry.

-n Shows what would be done, but doesn’t actually add entries. Useful for debugging in conjunction with –v.

-v Uses verbose mode, with many diagnostics written to standard output.

-c Continuous operation mode. Errors are reported, but LDAP continues to delete entries. The default is to exit after reporting an error.

-d level Sets the LDAP debugging level to level. ldapdelete must be compiled with LDAP_DEBUG defined for this option to have any effect.

-f file Reads a series of lines from file instead of from standard input, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern where the first occurrence of %s is replaced with a line from file.

-D binddn Uses binddn to bind to the X.500 directory. binddn should be a string-represented DN as defined in RFC 1779.

See http://www.rfc-editor.org/rfcsearch.html

-w passwd Uses password as the password for simple authentication.

-h host Specifies an alternate host on which the LDAP server is running.

-p port Specifies an alternate TCP port where the LDAP server is listening.

dn Distinguished name of the entries to be deleted. Each DN should be a string-represented DN as defined in RFC 1779.




ldapmodifyThe ldapmodify command allows you to modify entries to the Directory database. It is an LDAP utility originally developed by the University of Michigan and adapted by Software.com.

Syntax

ldapmodify [-a] [-b] [-c] [-r] [-n] [-v] [-d level] [-D binddn][-w passwd] [-h host] [-p port] [-f file]

Where:

-a Modifies existing entries. In ldapadd, this flag is automatically set to add new entries.

-b Assumes that any values that start with a ’/’ are binary values, and that the actual value is in a file whose path is specified in the place where values normally appear.

-c Continuous operation mode. Errors are reported, but ldapadd will continue to operate with modifications. The default is to exit after reporting an error.

-r Replaces existing values by default.



-d level Sets the LDAP debugging level to level.





-f file Reads the entry modification information from file instead of from standard input.



ldapmodrdnThe ldapmodrdn command allows you to modify the relative distinguished name (RDN) of one or more entries in the Directory database. It is an LDAP utility originally developed by the University of Michigan and adapted by Software.com.

Syntax

ldapmodrdn [-r] [-n] [-v] [-c][-d level][-D binddn] [-w passwd][-h host] [-p port] [-f file] [dn rdn]

where:

-r Removes the old RDN values from the entry. The default is to keep the old values.



-c Continuous operation mode. Errors are reported, but LDAP continues to modify entries. The default is to exit after reporting an error.

-d level Sets the LDAP debugging level to level. ldapmodrdn must be compiled with LDAP_DEBUG defined for this option to have any effect.






dn rdn Distinguished name / relative distinguished name pair for the entries to be deleted. rdn replaces the RDN of the entry specified by the DN, dn.

Each DN should be a string-represented DN as defined in RFC 1779.




Example

Assuming that the file tmp/entrymods has the follwing contents:

cn=Modify Me, o=Software.com, c=US cn=The New Me

the command

ldapmodrdn –r –f/tmp/entrymods

changes the RDN of the Modify Me entry from Modify Me to The New Me and removes the old cn, Modify Me.

ldapsearchThe ldapsearch command allows you to perform a search using a specified search filter. The filter should conform to the string representation for LDAP filters defined in RFC 1558. See http://www.rfc-editor.org/rfcsearch.html.

If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attrs are listed, all attributes are returned.

ldapsearch is an LDAP utility originally developed by the University of Michigan and adapted by Software.com.

Syntax

ldapsearch [-n] [-u] [-v] [-t] [-A] [-B] [-L] [-d level] [-F sep][-f file] [-D binddn] [-w passwd] [-h host] [-p port] [-b][-s scope] [-a deref] [-l time limit] [-z size limit] filter [attrs]

Where:

-n Shows what would be done, but doesn’t actually do the search. Useful for debugging in conjunction with –v.

-u Includes the user friendly entry names in the output.


-t Writes retrieved values to a set of temporary files. This is useful for dealing with non-ASCII values such as jpegPhoto or audio.

-A Retrieves attribute names only (no values). This is useful when you want to see if an attribute is present in an entry, but are not interested in the specific values.

-B Does not suppress the display of non-ASCII values. This is useful when dealing with values that appear in alternate character sets such as ISO-8859.1. This option is implied by –L (see below).

-L Displays search results in LDIF format. This option also turns on the –B option and causes the –F option to be ignored.



-d level Sets the LDAP debugging level to level. ldapmodrdn must be compiled with LDAP_DEBUG defined for this option to have any effect.

-F sep Uses sep as the field separator between attribute names and values. The default separator is =. If the –L flag is specified, this option is ignored.

-f file Reads a series of lines from file instead of from standard input, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern where the first occurrence of %s is replaced with a line from file. If file is a single-character, then the lines are read from standard input.






-b Uses as the starting point for the search instead of the default.

-s scope Specifies the scope of the search. scope should have one of the following values:

base – specifies a base object search

one – specifies a single level search

sub – specifies a subtree search

The default is sub.

-a deref Specifies how alias dereferencing is done. deref should have one of the following values:

never – specifies that aliases are never dereferenced

always – specifies that aliases are always dereferenced

search – specifies that aliases are dereferenced when searching

find – specifies that aliases are dereferenced only when locating the base object for the search.

The default is never.

-l time limit Waits at most timelimit seconds for a search to complete.

-z size limit Retrieves at most sizelimit seconds for a search to complete.

filter Specifies a search filter that conforms to the string representation for LDAP filters as defined in RFC 1558.

attrs Specifies the attributes to be retrieved, separated by white space. If no attribute list is given, all are retrieved.


4General Administration Utilities

InterMail messaging system supports a command line interface, with commands that allow the user to perform tasks such as:

• Starting and stopping the InterMail servers

• Reporting statistics on server usage

• Retrieving account information

• Modifying accounts and mailboxes (i.e. message stores)

• Analyzing and fixing corrupted messages

Note: For information on imdbcontrol, see “imdbcontrol” on page 207.

Unless otherwise specified by their absolute paths, all directories in this manual are relative to the InterMail installation directory (for example, tmp refers to $INTERMAIL/tmp, not to the root /tmp of your operating system). In addition, although you may have specified directory names different from the installation defaults, this chapter uses the default entries during installation, such as spool.

Note: This chapter uses the expression mailbox and message store to denote the container where messages are maintained for each user. While mailbox is the common term for this container, the IMAP protocol uses the concept of a mailbox in a different manner than the POP protocol; therefore, command arguments are typically described using “message store” to make them generic and independent of the retrieval protocol used.

Command DescriptionsThis chapter has a list of each command in alphabetical order by name, with a short usage statement, a list of all available arguments to the command (command syntax), a description of these arguments, and a short example. However, while this chapter lists all the commands, some commands are very complex. In these cases, only the usage and available arguments associated with these commands are shown in this



chapter; detailed examples are in the InterMail Kx Operations Guide. If you would like to see commands grouped by functionality, also refer to the InterMail Kx Operations Guide.

Note: Documentation for InterMail administrative commands is also available as man pages.

��!

You use the imbadmsgfix command when the InterMail MTA receives a message but the POP server cannot retrieve it. This may be because the message is corrupted or because some problem has occurred between the application software and InterMail. In any event, the system creates an .ERROR folder for the user’s message store to hold the message (or messages). Running imbadmsglist displays the contents of .ERROR folders. You then manually examine and fix these messages. After fixing these messages, imbadmsgfix runs to move the corrected messages to the user’s INBOX folder.

The imbadmsgfix command instructs the system to read a file (that imbadmsglist generates) identifying the contents of all .ERROR folders, and move those messages into the INBOX folder for the message store(-es) it lists. If you include the -v option, it checks messages for validity before moving them back into the INBOX folder. It will not move messages that fail this check.

Note: You can execute imbadmsgfix without the -v option; however, it is not advisable because messages that really aren’t fixed may move back to the user’s INBOX.

Syntax

imbadmsgfix [-v] <filename>

Where:

Example

To process fixed messages (in this case, messages that were in a file called “bad” and that you fixed manually), run imbadmsgfix as in the following example:

-v Verbose mode: performs validity checking on all message files to ensure that they are correct before they move back to a user’s INBOX.

<filename> File containing all messages in .ERROR folders. The imbadmsglist command produces this file.

paris% imbadmsgfix -v bad

imbadmsgfix:2................................................................................................. 0 messages still in .ERROR

General Administration Utilities


��(�!��

The imbatchextract command allows you to extract LDIF information from existing mail accounts that can be used as input for imbatchload. For more information on imbatchextract, see Chapter 4.

��(��

The imbatchload command allows you to load an input file containing LDIF formatted information. This file is either 1.) generated by imbatchextract and subsequently hand-edited or 2.) manually constructed as a sitestartup.batch file. For more information on imbatchload, see Chapter 4.

��!��

The imboxcreate command creates an InterMail mailbox. When the configuration database enables mailbox creation on the fly, the system creates message stores upon the first POP or MTA transaction that affects a user who does not already have a message store. However, if mailbox creation on the fly has been disabled in the configuration database, you can use imboxcreate to create the message store.

When you use imboxcreate to create a message store for an InterMail user, you must specify the host and the Internal ID for the user (you may use imdbcontrol to determine this information).

Optionally, you may specify a quota value for the total allowable bytes in this message store (<TotalBytes>).

Syntax

imboxcreate [-help] [<host>] <InternalID> [<TotalBytes>]

where:

Example

To use imboxcreate to create a message store, run imboxcreate as in the following example:

-help Provides usage statement.

<host> Host upon which the message store resides.

<InternalID> Message Store ID.

<TotalBytes> Maximum number of bytes for this message store.

paris% imboxcreate paris 123456 1000000

imboxcreate: Message store 123456 created!



Note: Setting up an initial TotalBytes quota with imboxcreate does not prohibit you from increasing or decreasing that value at a later time. If you do not specify the quota, it defaults to 0, which means no quota or “unlimited.”

��!��

The imboxdelete command deletes an InterMail message store.

Note: Deleting an InterMail message store is NOT the same as deleting an account. Please refer to the InterMail Kx Operations Guide for more information on how to delete an account.

Syntax

imboxdelete [-v] [-a|-m <file>] <host> <InternalID>

where:

Note: You can find the Message Store ID and the name of the MSS host for a given e-mail address with the imboxget command.

Example

To delete a message store, run imboxdelete as in the following example:

��!��

The imboxget command reports the Message Store ID and the name of the MSS host holding mail for a specified user.

Syntax

imboxget <e-mailAddress>

-v Verbose operation.

[-a <file>] An input file containing e-mail addresses.

[-m <file>] An input file containing Message Store IDs.


<InternalID> Message Store ID.

paris% imboxdelete paris 654321

imboxdelete: Message store 654321 deleted!



Where:

Example

To find out the host and Message Store ID for a particular user, run imboxget as in the following example:

��!��

The imboxstats command reports the current volume of mail stored in a given message store. The message store is identified by the pair (host/Internal ID, host/MessageStoreName, host/e-mail address).

Syntax

imboxstats [-v] {<MessageStoreName> | <e-mailAddress>}

where:

Example

In this example, Broc’s message store has 112 messages totaling 2613599 kb. There are no quotas set on this message store.

��!��

The imboxtest command checks connectivity to a message store using the POP server. imboxtest tests whether the POP server is running and functioning properly, whether the directory account is properly set up, whether the POP server is able to communicate with the Message Store Database, and if the message store is functioning properly.

<e-mailAddress> Valid e-mail address.

paris% imboxget [email protected]=earth Message store=1000

-v Verbose execution.

<MessageStoreName> Name of a Message Store.

<e-mailAddress> A valid e-mail address.

paris% imboxstats [email protected] for [email protected] are totalMsgs=112/MsgsQuota=0, totalBytes=2613599/BytesQuota=0paris%



Syntax

imboxtest <host> <LoginName> <Password>

Where:

Example

To test a user’s ability to connect to a message store from a POP session, run imboxtest as in the following example:

This example shows a successful response for the POP server. First, it makes a connection to the POP server and issues a series of POP3 commands.

Next, it sends the USER command to identify the user to the POP server, using the user name you provided on the command line. The POP server uses this name to look up information about this user in the Directory. Then it issues the PASS command, sending the password that you provided on the command-line. This verifies to the POP server that this password is correct and allows access to the message store indicated. These first two commands test the POP server’s connectivity to the Directory. Then, imboxtest issues a STAT command. This lists the number and total size of messages in the message store. This tests the functioning of the MSS host. Finally, imboxtest issues the QUIT command to end the POP session cleanly.

Note: If you enter an incorrect LoginName or Password, or if a communication problem occurs with the POP or IMAP server, then it will display an error.

��*��

The imbucketscreate command has three applications related to the Message File System. Initially, when installing InterMail, imbucketscreate creates the Message File System where messages will be stored.

As a second application, imbucketscreate distributes message files evenly in the directories of the Message File System. This function helps performance when the system reads message files from, or writes message files to, individual directories. cron automatically runs this application of imbucketscreate periodically.

Finally, imbucketscreate can expand the Message File System as necessary after you create it.

<host> Name of the host running the POP or IMAP server.

<LoginName> POP or IMAP login name for a user.

<Password> Password of the user.

paris% imboxtest paris john.doe $ecret

+OK InterMail POP3 server ready+OK please send PASS command+OK john.doe is welcome here+OK 152 1928370+OK john.doe Intermail POP3 server signing off.



Syntax

imbucketscreate [<dir> <c1...cn>]

Where:

Example

To expand the Messsage File system to include an additional subdirectory, enter the following:

��

The imcmdlist command prints a list of all InterMail commands and a short description to standard output.

Syntax

imcmdlist

Example

To produce a list of available commands in InterMail, run imcmdlist as in the following example:

<dir> Relative path to an existing directory to create directly under the directory in mss/messageFilesDir.

<c1...cn> A series of one or more positive numbers representing the number of subdirectories at each level below <dir>.

paris% cd msgfilesparis% lsmessages buckets buckets.dirparis% mkdir messages_2paris% pwd/vol1/imail/msgfilesparis% ../lib/imbucketscreate messages_2 10 10imbucketscreate: creating 100 directories under msgfiles_2.imbucketscreate: finished creating 100 directories under msgfiles_2.paris% lsmessages messages_2 buckets buckets.dirparis% more buckets.dirmessagesmessages_2paris% ../lib/imbucketscreate

paris% imcmdlist

Command Name Description____________ ___________ imbadmsgfix Moves messages from .ERROR folder to inboximbadmsglist Lists to file those messages in the .ERROR folder imboxcreate Creates mailboxesimboxdelete Deletes mailboxes ............



��

The imconfcontrol command installs changes made to a configuration database and we mention it here for completeness. However, it is reserved for specific maintenance conditions and you should use it only in conjunction with your vendor or technical support.

��

The imconfedit command allows the user to view or change the configuration database. It invokes the imconfget, imconfcontrol, and imconfxlate scripts, reading either the default configuration database file (config.db) or one that you specify on the command-line. A text editor, set by the $EDITOR or $VISUAL environment variables, displays the configuration database. At this point, the user can edit or view the configuration information, evaluate the effect of editing on the system, and propagate these changes throughout the system.

Although an InterMail system can consist of numerous hosts and each host contains a local copy of the configuration database, the configuration database uses a “centralized configuration” mechanism. Typically, you only edit one config.db file. This master configuration database will be the config.db of the host that you have designated as the Master host.

Syntax

imconfedit [-help] [-x] [-viewonly] [-onpipe] [-getConfigDB -f <outputFile>]] [-putConfigKeys]

Where:

-help Provides usage statement.

-x Executes imconfedit in verbose mode; shows all program invocations that imconfedit calls as they execute.

-viewonly Invokes a read-only copy of the config.db file in vi or other editor defined by $EDITOR or $VISUAL variable.

-onpipe Used when a secondary script will invoke imconfedit and needs to understand the current status of imconfedit.

-getConfigDB-f <outputFile>

Causes imconfedit to perform necessary local copy and configuration server locking while extracting a copy of the configuration database.

-putConfigKeys Allows you to specify the keys and their new values that you want to insert into configuration database. This option also ensures that all the necessary locking and unlocking is done.



Example

To modify the configuration database, run imconfedit as in the following example:

paris% imconfeditimconfserv is running on paris

imconfedit first checks to make sure the configuration server, necessary for editing and propagating changes to InterMail, is running. Next, the vi editor displays the configuration database file that you can edit.

After you finish making changes and exit the editor, imconfedit will review the changes you made and ask you whether you wish to assess these changes:

If you type “r” (re-edit), the vi editor reopens and you can review your changes or make new changes that you may have omitted in your first editing pass. If you type “q” (quit), imconfedit will exit and save your changes to a file in the format

config.db.<date/time-stamp>

in the config directory. You can later reintroduce this file with imconfedit <filename>.

/*/common/abortIfLogFails: [false]/*/common/badPasswordDelay: [5]/*/common/badPasswordWindow: [120]/*/common/cacheLimitInKB: [256]......

The changes you have made are:----------------------------------------------------------------------12c12< /*/common/dirCacheConnections: [40]---> /*/common/dirCacheConnections: [39]----------------------------------------------------------------------

Do you want to assess the changes now (Re-edit/Quit) [Proceed] ?



If you press Enter or type “p” (proceed), it will inform you what server actions will be necessary to make your changes throughout the InterMail system:

If you type “r”, then it will display the configuration file again in vi. If you type “q”, it will save the file as previously described. If you press Enter or type “p”, then imconfedit will make the necessary changes and, if you desire, restart all necessary servers.

Note: Although imconfedit has the ability to restart servers, typically this is a manual operation to perform at an off-peak time or during a maintenance window. Instead, use imservctrl or imctrl to restart servers.

Notice that imconfedit will not successfully complete until you have reviewed changes, the system has made assessments on the servers, and servers have restarted (either manually or through imconfedit).

“* Impacts of Changes:----------------------------------------------------------------------* ******************************************************************************* Servers Needing Re-starting* ******************************************************************************* imapserv on paris (dirCacheConnections): requires a re-start* imconfserv on paris (domainName): requires a re-start* mss.1 on paris (dirCacheConnections): requires a re-start* mta on paris (dirCacheConnections): requires a re-start* popserv on paris (dirCacheConnections): requires a re-start* ******************************************************************************* Parms Not Yet (if ever) Fetched* ******************************************************************************* imconfserv on paris (journalDir): has not yet been fetched----------------------------------------------------------------------

Do you want to install the changes now (Re-edit/Quit) [Proceed] ?

---- The changes have been made on the config server ----Do you want to re-start the servers now? (Y/N) yexecuting “imctrl paris restart imapserv:imconfserv:mss.1:mta:popserv”



Warning! You should always edit the master configuration database; if you need to enter host-specific keys, simply add them to the configuration database. For example, if you have a master host named “paris” and there is an additional POP host named “lisbon,” simply specify additional host-specific configuration keys on paris as in the following example:

Configuration management contains much more information than is shown in the imconfedit or related commands.

��

The imconfget command displays the value of one or more configuration keys.

Syntax

imconfget [-localconfig][-s][-c][–n][-fullpath][-m <module>][-d <default>]<key>[<key>…]imconfget [-h <host>] -serversimconfget -hostsimconfget -server <name>

where:

/*/common/abortIfLogFails: [false]/earth/common/abortIfLogFails: [true]....../*/common/clientHeaps: [16]/earth/common/clientHeaps: [13]

-localconfig Queries the configuration database on the local host. If you omit this flag, imconfget retrieves an up-to-date configuration database from the Configuration Server before executing the query.

-s Formats output so that both key name and value echo to standard output.

-c Outputs directory values defined relative to $INTERMAIL as full path.

-n Multi-valued (list-valued) configuration keys use a newline as the list item separator; ordinarily imconfget just prints them as they are, with one value per line. The -n option causes imconfget to replace the newlines with “\n”.



Example

To get the value of a single configuration key, run imconfget as in the following example:

��!��

The imconfxlate command modifies a configuration database and we mention it here for completeness; however, it is reserved for specific maintenance conditions and you should use it only in conjunction with your vendor or technical support.

-fullpath Configuration key defined in the <key> parameter is a full configuration path (that is, /<host>/<server>/<key>). If omitted, imconfget assumes that the key has no host or server path, and queries the configuration database for the key under the path:

/<localhost>/common/<key>

For example, if you execute imconfget on the host paris, and search for the key binDir, omitting the –fullpath flag causes imconfget to search for the key at:

/paris/common/binDir

Including the -fullpath flag prevents adding the host and server path to the given key.

-m <module> Server name portion of the queried configuration entry. Possible values for this parameter are: httpd, mta, mss, imdirserv, popserv, imapserv, imconfserv, immgrserv, sysadmin, or common.

-d <default> Options for returning a “default” value if it does not find an entry. When you use this option, and the queried key does not exist in the configuration database, it returns the value given after the -d flag.

<key> Name of the specific configuration key.

-servers List of names of all servers specified in the configuration database.

-hosts List of names of all hosts specified in the configuration database.

-server <name> List of names of all hosts in the configuration database that have keys associated with a specific server process (<name>).

paris% imconfget -h paris -m common binDirbin



��

The imctrl command controls servers on a local or remote host, allowing the user to remotely control the operation of InterMail.

Syntax

imctrl [-verbose] {<host>[:<host>]|localhost|allhosts} {start|drain| stop|kill|restart|drainStart|stopStart|exitStart|killStart} {<server>[:<server>:<server>]|mailservers|allservers} [-dryrun]

Where:

-verbose Verbose execution.

<host> Host machine (or list of colon-separated hosts).

localhost Host machine that the imctrl command executes on.

allhosts All hosts in the InterMail system.

start Starts the designated server or servers.

drain Drains the specified server(s), causing it/them to refuse any new work assignments, complete those assignments in process, and then exit.

stop Stops a server as soon as possible: interrupts client sessions, and displays error or status messages to clients.

kill Kills a server process as soon as possible (similar to kill -9).

restart Stops and then restarts the affected server(s).

drainStart Drains and then restarts the affected server(s).

stopStart Stops and then restarts the affected server(s).

exitStart Stops and then restarts the affected server(s).

killStart Kills and then restarts the affected server(s).

<server> InterMail server (or list of colon-separated servers).

mailservers All servers that affect the processing of mail (this excludes immgrserv and imconfserv).

allservers All servers in the InterMail system except immgrserv (namely, httpd, imapserv, imconfserv, imdirserv, immgrserv, mss, mta, and popserv).

-dryrun Displays information on what steps the system would perform with the specified imctrl invocation, but does not actually perform these steps.



Example

To control the behavior of servers in the InterMail system remotely, run imctrl as in the following example:

To execute multiple sets of arguments, run imctrl as in the following example:

��

The imdbcontrol command allows you to modify the contents of the database. For information on imdbcontrol, see Chapter 4.

��*�

The imdbmake command is used to manipulate the Message Store database. It is mentioned here for completeness; however, it is reserved for specific maintenance conditions and you should use it only in conjunction with your vendor or technical support.

��*�

The imdirmake command is used to manipulate the Directory database in the Integrated Services Directory. It is mentioned here for completeness; however, it is reserved for specific maintenance conditions and you should use it only in conjunction with your vendor or technical support.

��

The imdbrecover command is used to recover database information previously backed up using imconfcontrol with backUp mode enabled and an archiving procedure (such as tar).

Syntax

imdbrecover [-h][-m|-d]

where:

venus% imctrl localhost restart mta

venus% imctrl earth restart mta:mss venus start mta venus kill popserv

-h Produce usage information.

-m Restore Message Store database and message file system information.

-d Restore Directory database information.



9��(��*

The imfiltercheck command allows the user to apply a filtering rule set based on the SIEVE language which, when executed, can bounce, sideline, forward, discard, or deliver incoming mail normally, based on content.

Syntax

imfiltercheck {-v <filterFile> ...|-vi |-vc <key> |-e [<filterFile>|-c <key>] <messageFile> ... |-es [<filterFile>|-c <key>] <headerFile> <bodyFile> |-ei [<filterFile>|-c <key>] < <messageFile>}

Where:

Note: See the InterMail Kx Operations Guide for examples of how to use imfiltercheck.

��

The imfolderlist command retrieves all messages in a message store and prints their headers to standard output. The imfolderlist command lists the header information for all messages in a specified message store’s INBOX folder. The INBOX is where all messages are originally stored upon delivery from the MTA. The INBOX is also the only folder that the POP protocol supports.

-v Validates one or more filters (as specified in files).

-vc Validates a filter (as specified in a configuration key).

-vi Validates a filter (taken from standard input).

-e Executes the given filter on a message (defined in a single file).

-es Executes the given filter on a message (defined in a body and header file).

-ei Executes the given filter on a message (taken from standard input).

<filterFile> File that contains the filter to validate.

key Configuration key that contains the filter to validate. The value is typically the incomingMailFilter configuration key.

<messageFile> Message file to execute the filter on.

<headerFile> Header file to execute the filter on.

<bodyFile> Body file to execute the filter on.



Syntax:

iminboxlist {<MessageStoreName> | <e-mailAddress>} [-folder <folderName>] [-s][-d][-all | <attribute>]

where:

Note: In addition to the standard headers shown with the attribute option, you may include additional client- and server-specific headers for a given message. The header output for each header attribute consists of a message index, a colon followed by the header attribute type (for example, From), a colon and the value of the header attribute. A blank line separates the output for each message.

��!��

The iminboxlist command lists the header information for all messages in an INBOX folder of a specified message store. The INBOX is where the system stores all messages upon delivery from the MTA. The INBOX is also the only folder that the POP protocol supports.

Syntax

iminboxlist <host> {<MessageStoreName> | <e-mailAddress>} [-all | <attribute>]

Where:


<e-mailAddress> A valid e-mail address.

-folder <folderName> The name to list (/INBOX by default).

-s Also list messages in all subfolders of <folderName>.

-d If command fails, produce detailed error messages.

-all Indicates that all of the header attributes should be printed. The default is to print out the From, Subject, Message-ID and Date attributes.

<attribute> Indicates zero or more header attributes. The available attributes include the following: From, To, Subject, Date, cc, bcc, Message-ID, Received, Reply-To, Resent-To, Resent-From, Resent-Date.






Example

To report header information, run iminboxlist as in the following example:

Note: The difference between imfolderlist and iminboxlist is that imfolderlist is able to list the contents of any IMAP folder, whereas iminboxlist will only list the INBOX.

��

The imlogprint command runs as a UNIX filter, reading standard input and writing to standard output. The expected input is lines from a log, stat, or trace file. It formats output, so that it is much more readable than viewing the raw log file and does not require prior knowledge of the error Message IDs.

imlogprint presents log file (including stat file and trace file) information to the user in a format that is less terse and more readily understandable. You usually run this after pre-filtering the logs to remove unwanted entries. You can include or exclude log entry fields (that you specify by a single number, series of numbers, or range of numbers indicating the field(s)) from the output. The date field is by default in American format (namely 1/31/1997), but can be in European format (namely 31.1.1997). The output prints on one line by default, but you can make it multi-line (-m), which makes it easier to read. In addition, the fields can have tags, to clarify the meaning of each field.

Note: When you are finished with imlogprint, enter ^D to kill the process.

Syntax

imlogprint [-f <value> [...<value>]][-x <value> [...<value>]][-l][-e][-t][-m][-h][< <logFile>]

Where:

-all Prints all the header attributes. The default is to print out the From, Subject, Message-ID and Date attributes.

<attribute> See attribute description and note following imfolderlist.

paris% iminboxlist paris [email protected] From Subject

0: From: [email protected] (John Doe) 0: Subject: What’s going on, Susie?

-f <value> A number or series of numbers to indicate which fields to include when printing to standard output.

-x <value> A number or series of numbers to indicate which fields to exclude when printing to standard output.



Example

To format log output from standard input with sample arguments, run imlogprint as in the following example:

To format log output from standard input and place entries on multiple lines with tags, run imlogprint as in the following example:

Finally, to format log output and exclude certain fields from summarization, run imlogprint as in the following example:

-l Outputs the local time of the host machine.

-e Converts date to “eurodate.”

-t Places descriptive tags in the beginning of each output field.

-m Places output on multiple lines.

-h Prints help statement.

<logFile> Log file to use as input.

paris% imlogprint -m

19980316 142216530-0800 paris immgrserv 28322 4 6 Note;ConfServerLock(51/59) 28689:paris:locked

03/16/1998 14:22:16.530-0800 paris immgrserv 28322 4 6 Notification;[ConfServerLock] The process 28689 on host “paris” has locked the configuration server.^D

paris% imlogprint -t -m

19971021 021512922 paris popserv 14812 7 14 Note;PopProtocolErr(66/1) AUTH twinkie:cmd=AUTH twinkie

date=10/21/1997 time=02:15:12.922 GMT host=paris prog=popserv pid=14812 lwp=7 thread=14 sev=Notification;[errorCode=PopProtocolErr] A POP protocol error occurred during session: POP cmd: “AUTH twinkie”. cmd=AUTH twinkie

paris% imlogprint -t -m -x 1-2

19971021 021512922 paris popserv 14812 7 14 Note;PopProtocolErr(66/1) AUTH twinkie:cmd=AUTH twinkie

host=paris prog=popserv pid=14812 lwp=7 thread=14 sev=Notification;[errorCode=PopProtocolErr] A POP protocol error occurred during session: POP cmd: “AUTH twinkie”. cmd=AUTH twinkie



While the default behavior for imlogprint is to enter a log entry from standard input, you may use imlogprint on an entire log file by directing a named log file into imlogprint in the following manner:

If you choose this option, you will probably want to redirect this output to a second file (namely, mta.log.printout).

��

The imlogsum command processes log and stat files to produce a summary of events occurring in the log files. The statistics pertinent to each log file print to standard output as soon as it processes the file. At the end of the run imlogsum prints the cumulative information for all files processed. You can supply the names of the files to process either on the command line, or interactively, or both ways simultaneously.

Syntax

imlogsum [-l <severity>] [-h] [-v] [-s | <logFile>] [<logFile> ... ]

Where:

paris% imlogprint -t -m < mta.log

-l <severity> Lowest level of severity to process (0: notification, 1: warning, 2: error, 3: urgent, 4: fatal).

-h Prints usage statement.

-v Verbose mode.

-s Sticky mode: after processing all files on the command line (if any), reads the standard input for names of the files to process.

<logFile> Name of the log file to use as input.



Example

To produce a summary for a log file, showing all events of at least notification (-l notification) severity, run imlogsum as in the following example:

��

The immsgdelete command deletes one or more messages from a message store. Printed output includes each message to delete and one warning message for all the messages that it could not delete. Since immsgdelete interacts with the Message Store Database, you must use the Internal ID and host to identify the message store.

In addition to specifying the message store you want to act upon, you also must specify the message(s) you want to remove. To determine the Message IDs of some of the messages in the message store, you can run the iminboxlist command, which will list all of the messages in an INBOX.

Syntax

immsgdelete {<host> <MessageStoreName> | <e-mailAddress>} {<msgID>...|-all}

Where:

paris% imlogsum -l notification mta.log

File ‘mta.log’ { 242: MsgTrace 121: SmtpConnectionClosed 121: SmtpConnectionReceived}

********** Totals of messages in ‘.log’ files **********

242: MsgTrace 121: SmtpConnectionClosed 121: SmtpConnectionReceived

********************************************************************




<msgID> Name(s) of message(s) to delete. This name comes from iminboxlist and must be in the format ‘<Message-ID>’.

-all All messages in the message store.



Example

To delete a message from a user’s message store, run immsgdelete as in the following example:

Note: Use iminboxlist to determine Message IDs.

��

The immsgdump command displays the actual messages stored in message stores. This command will print out the message header and body. An index specifies the particular message dumped. The index number starts at ‘0’; therefore, the first message in a user’s message store will have the ‘msgNum’ of ‘0’. You can determine this index number by running iminboxlist.

Syntax

immsgdump {<host> <MessageStoreName> | <e-mailAddress>} <msgNum>

Where:

paris% immsgdelete paris [email protected]’<[email protected]>’

Deleting msg 3 -- <[email protected]>




<msgNum> Number of the message to view (as identified by imfolderlist or iminboxlist).



Example

To show an actual message from a message store, run immsgdump as in the following example:

��

The immsgfind command finds one or more Message Numbers in an InterMail message store, given their Message IDs. The header line for the <msgID> attribute will print if it finds the Message ID. If it did not find a message with a matching Message ID, it prints a warning.

Note: See imboxcreate for information on Internal IDs versus SMTP addresses as stored in the Integrated Services Directory. See immsgdelete for more information on Message IDs.

Syntax

immsgfind {<host> <MessageStoreName> | <e-mailAddress>} <msgID> [...<msgID>]

Where:

paris% immsgdump paris [email protected] 1

Received: from earth.software.com ([1.2.2) by paris.software.com (InterMail v3.1 117) with ESMTP id <[email protected]> for <[email protected]>; Thu, 23 Oct 1997 20:15:26 -0700Date: Thu, 23 Oct 1997 23:16:57 -0400 (EDT)From: [email protected]: <[email protected]>To: [email protected]: Have you seem Susie?

Have you seen Susie Queue? She was waiting at the printer, but after the job printed, she went away.-john




<msgID> One or more messages to find in the user’s message store. This name comes from iminboxlist and must be in the format ‘<Message-ID>.’ As with immsgdelete, you specify the Message ID with leading and ending single quotations and brackets.



Example

To find out a message number, run immsgfind as in the following example:

��

The immsgmassmail command sends a single message to a group of recipients. The message and the recipients must be stored in files with a standard format. The recipients file must contain a single e-mail address per line. Blank lines, leading and trailing whitespace, and “” comments are ignored.

The immsgmassmail command can run only on a host which is configured to run the MTA.

Syntax

immsgmassmail [-f <e-mailAddress>] <recipientsFile> {<messageFile> | - }

Where:

Example

You can execute the immsgmassmail command in two ways: either by creating a message file or by entering a message through standard input. The following example shows a properly formatted message file:

The message file must contain at least three headers: “From:,” “To:,” and “Subject.” If any of these headers is missing, or if any of them shows up more than once, the script will exit with an error. The contents of the “From:” header should be a valid e-mail address that the recipients can use when replying to your message. The contents of the “To:” header will not be an e-mail address, since you will specify the recipients-list to

paris% immsgfind paris [email protected] \ ’<[email protected]>’

3 : Message-ID: <[email protected]>

-f <e-mailAddress> Sender’s e-mail address.

<recipientsFile> List of e-mail addresses.

<messageFile> E-mail message to send.

- Invokes standard input mode.

From: [email protected]: Our Valued UsersSubject: Routine Maintenance

All mail services will be unavailable from 3:00am to 3:30amtonight while we upgrade our services. We appreciate your patience while we improve our system to serve you better.

Regards,Your Systems Administrators



contain e-mail addresses comprising your intended audience. immsgmassmail will also insert three other headers if they are not already present in the message file: Message-ID, Date, and X-Mailer. After specifying the message headers, the next line must be empty. All remaining lines constitute the body of the message.

To send a message (that you create in a file called to.list) using standard input mode, run immsgmassmail as in the following example:

After typing the message headers, entering a blank space, and typing the message body, you must exit standard input in a specific manner: enter a carriage return and then type ^D. After exiting standard input mode, immsgmassmail will save the message in a date-time stamped file in the tmp directory and echo the recipients of the message.

If standard error has alerted you that some recipients have not received the message, then you should rerun the command in the following manner:

1. Edit the recipients-file to include only the names of recipients who have not received the message.

2. Run immsgmassmail again, using the message file saved in the tmp directory (as the messageFile).

Note: If a sender is not specified with the -f option, an empty address, "<>",will be used as the sender

��

The immsgprocess command resubmits control files that the system has sidelined or moved to the .ERRORS directory. The program works by simply moving the control file into the deferred directory on the Queue Server, which the MTA scans periodically. It also modifies the control file to have the correct “Header-File:” and “Body-File:” lines. The header and body files move into the appropriate bucket directories. With immsgprocess, the user can use either the Control file name; Control and Header; or Control, Header, and Body file name(s) to reintroduce the messages.

paris% immsgmassmail to.list -

From: [email protected]: john.doe, susie.queueSubject: Do not interfere...

Are you guys coming to lunch?^D

immsgmassmail: Notice: saved message in "/vol1/imail/tmp/immsgmassmail.980519210155.9522"[email protected]@paris.software.com



Syntax

immsgprocess <controlFile> [<headerFile> [<bodyFile>]]

Where:

��

The immsgverify command prints a list of all “widows” and “orphans” to standard output. “Widows” are messages in the database that have no corresponding message files in the Message File system. “Orphans” are files in the Message File system for which no database entries can be found. Since the immsgverify command needs to compose complete lists of messages in both the database and the Message File system, it usually takes a long time to run.

After doing the first comparison, immsgverify makes a second pass for orphans in the process of being created and currently linked into the database.

It creates one text listing file for orphans and another for widows. Each listing file holds the paths to the extra or missing message files. If it finds problems, it reports the names of the listing files to the console. If it does not find any orphans or widows, it simply removes the empty listing file.

Using the listing file, you can simply delete orphans manually from the appropriate Message File system directory. Widows are a more serious problem. If possible, restore missing message files to the Message File system using imjrnrecover. If that is not possible, use immsgdelete to delete the messages from the Message Store Database.

The immsgverify command has no options or parameters. You run it as the imail user on a Message Store Server (MSS) host.

Example

To check for widows and orphans, run immsgverify as follows:

<controlFile> Control file to specify for reprocessing.

<headerFile> Header file to specify for reprocessing.

<bodyFile> Body file to specify for reprocessing.

paris% immsgverify

find: path-list predicate-list

immsgverify: widows found, see /vol1/imail/tmp/immsgverify.22184.widows



��

The immsinit command creates a welcome message to greet new users and to inform them of system policies, quotas, and so forth.

Syntax

immsinit [-he[lp]][-ho[st] <host>][-w <welcomeMsgFile>] [-a <adminID>]

Where:

Examples

To create an administrative message store with a welcome message, run immsinit as in the following example:

The –a <adminID> flag is used with the immsinit command to indicate the Message Store ID of the Administrative User. By default, the Administrative User is the postmaster. If you want to designate someone other than the postmaster as the Administrative User, change the default value using the -a <adminID> flag.

Alternately, to create the administrative message store, you may use immsinit with the –w argument. This argument allows you to specify a message in a text file. In order to perform this procedure, you may need to edit the /*/welcomeMsgId key to a unique value (such as the combination of “Welcome” and a datetime stamp); for example, <Welcome.042899>. Next, format the welcome message with a From:, To:, Message-ID:, and Subject: header, as in the following:

-he[lp] Produces a help statement.

-ho[st] <host> (Optional) Host upon which the welcome message will reside.

-w <welcomeMsgFile> Text file that contains the welcome message, properly formatted with a “From,” “Subject,” and “Message-ID” header.

-a <adminID> Message Store ID of the admin user.

paris% immsinit

immsinit: connecting to MSS on parisimmsinit: Creating mailbox for adminimmsinit: importing a message for adminimmsinit: Finished building message store for admin

From: AdminTo: New UsersMessage-ID: <Welcome.042899> Subject: Welcome to Everyone!

=================================================================================

Welcome to InterMail by Software.com. This is your first electronic mail message.May you have many more!



��

The immsscall command creates and deletes message stores and we mention it here for completeness; however, you should use it only in conjunction with your vendor or technical support.

��(��*

The immtacheck command examines the state of the InterMail MTA message queue prints a report showing the number of messages in the system and their status.

Syntax

immtacheck [-d][-h][-p][-q][-s]

Where:

Note: If invoked with no arguments, immtacheck defaults to -dpqs

To show the state of the message queue and print a report of transactions in the MTA, run immtacheck as in the following example:

The summary goes through the queue/messages subdirectories looking for body files and counts how many are the same age. It groups them by hour if they are less than a day old, otherwise it groups whole days together.

The “currently being processed” messages are those found in the queue/control directory.

-d Shows how many dead letters are in the system.

-h Prints help message.

-p Reports how many messages the system is currently processing.

-q Shows detailed information about queued outbound messages.

-s Prints a summary of all messages in the system.

paris% immtacheck

Summary of all messages currently stored in the InterMail MTA Number Length of time in the system ------ ---------------------------- 0 Messages currently being processed: 0 Dead Letters that are not being processed Number Length of time in the system ------ ---------------------------- 1 19 hours 1 1 day ------ 2



Dead letters are messages that the system could not deliver and could not return to their senders. Their header, body, and control files are in spool/errors.

��(��

The imorphanrm command allows the user to remove MTA orphans safely without causing service interruption. The MTA does not need to be shut down or stopped in any way.

InterMail stores incoming messages in three files; a -Body, a -Header, and a -Control. An orphan is a -Body and/or -Header file with no corresponding -Control file. These are not the result of lost mail; rather, they can occur when the MTA is killed in the process of processing mail.

To guarantee safety, imorphanrm doesn’t remove any file, orphan or not, that is less than 30 minutes old. Additionally, imorphanrm makes two passes over the files to ensure that transient situations aren’t mistaken for orphan conditions. imorphanrm removes orphans from the MTA spoolDir.

Note: The imorphanrm command requires the -x option to execute, unless running in debug mode.

Syntax

imorphanrm [-d|-v|-s|-h|-x]

Where

��

The impopuserstats command reports the number of POP server transactions that occurred between the server and the specified user each hour. The impopuserstats utility parses the popserv.log files in the $INTERMAIL/$logDir directory. The output of the log file lists the number of POP user activities within each day and hour. The hour is printed as a single 24-hour number.

-d Debug mode. Indicates which files will be removed without

taking any action.

-v Verbose mode.

-s Summary mode. Summarize the files that were removed.

-h Produce help statement.

-x Execute mode. Required to run, unless debug mode is specified.



Syntax

impopuserstats <LoginName> [<logFile>...[<logFile>]]

Where

Example

Sample output appears below. The first number in each row is the number of transactions by testuser1 within a single hour. The next number indicates the date (in YYMMDD format). The third column indicates GMT time.

The output indicates that there were 2 user transactions logged by the pop-server on January 2, between 1:00 pm and 1:59 pm, one transaction that same day between 3:00 pm and 3:59 pm, and one between 4:00 pm and 4:59 pm. There was one transaction on January 3 between 2:00 pm and 2:59 pm, and four transactions on January 8 between 11:00 am and 11:59 am.

��(��(

The impwdhash command allows the user to store passwords in a “hashed” format. The impwdhash command takes clear-text strings as input and “scrambles” them, resulting in an apparently random binary string (called a “hash”) from which you cannot recover the original plain text. There is no way to “figure out” what this hashed password is by looking at either the cache or the database, because, unlike encryption, hashing is a one-way algorithm. The only way to return the clear-text equivalent value of a hash is to take another clear-text value, run it through the same hashing algorithm, and compare the result. If you have a match, you know that the new plain text matches the original plain text.

The system supports two forms of hashing: MD5-PO and UNIX [crypt() algorithm]. InterMail supports the capability to specify different hash schemes on a per-user basis. The Integrated Services Directory stores user passwords. The Integrated Services Directory also stores hashed passwords.

Note: Typically, you use the impwdhash command in conjunction with imdbcontrol to get and set hashed passwords (see the Chapter 4 for more information on imdbcontrol).

<LoginName> POP login name for a user.

<logFile> A single or multiple set of popserv.*.log files. You can specify <logFile> literally or specify it with a wildcard (such as popserv.paris.*).

paris% impopuserstats testuser1

2 970102 131 970102 151 970102 161 970203 144 970108 11



Syntax

impwdhash -a [md5-po|unix] <Password> [<hashedPassword>]

Where:

Example

To set a password, run impwdhash in conjunction with imdbcontrol, as in the following example:

Note: The following example includes the creation of a new user account. For more information on account creation, see the InterMail Kx Operations Guide.

In this example, we first have hashed the password “$ecret.” Then the hashed password and password algorithm are input into imdbcontrol as it creates the account. Now, although the hashed string “f3HiwyRyBcEX2” is in the Integrated Services Directory, you still see the “$ecret” password when identifying yourself to the POP server.

��7��

The imqueuesplit command allows the user to split outgoing e-mail queues. During some service periods, when the system cannot deliver outgoing e-mail because the remote domain is not available, it must defer the mail and outgoing mail queues can get very large. Deferred mail messages reside in outgoing queues: there is one queue for each unreachable remote domain.

Periodically, InterMail will scan all out-going queues. For each queue still containing deferred e-mail messages, InterMail will attempt to connect to the corresponding domain. Once InterMail successfully connects to the remote domain, it will attempt to deliver all messages in the queue, one at a time.

In a heavily loaded InterMail system, thousands of messages could accumulate in the deferred queue while the remote domain is rejecting connections. In this case, once the remote server is again accepting connections, it could take some time to deliver all the messages, since InterMail is only delivering one message at a time for each deferred queue. In order to get InterMail to deliver several messages to the same

-a Algorithm strategy to use for hashing.

md5-po MD5-PO hashing strategy

Unix UNIX hashing strategy

<Password> POP password for the account.

<hashedPassword> Hashed password.

paris% impwdhash -a unix $ecret

f3HiwyRyBcEX2paris% imdbcontrol createaccount john.doe [email protected] 25 jdoe f3HiwyRyBcEX2 unix



remote domain simultaneously, it is necessary to divide the mail in the deferred queue between several different queues. imqueuesplit will split these outgoing queues for reprocessing messages.

Syntax

imqueuesplit <destdomain> <newdest> [<newdest> ....]

Where:

��

The imreplyctrl command controls the auto-reply feature of InterMail. This feature automatically sends messages back to anybody who sends a message to an account that has the Auto Reply feature activated.

Syntax

imreplyctrl [vacation|reply|echo] <username> <domain> <messageFile>

imreplyctrl none <username> <domain>

imreplyctrl expire

Where:

<destdomain> Domain name for outgoing queued mail.

<newdest> Additional domain name(s) for outgoing queued mail.

vacation Sends a specific message back to the sender (Message-File). One message will go to each sender for the duration of the vacation period (set by the mss/autoReplyExpireDays configuration key).

reply Sends a specific message back to the sender (Message-File) each time a sender submits a message to the user.

echo Sends the user-defined message and the incoming message back to the sender.

none Discontinues autoreply mode for a specific user on a given domain.

expire Removes the old auto-reply history maintained for each user on the specified MSS host. If you do not specify a host, the default host is the one on which imreplyctrl is running.

<username> The local portion of a user’s e-mail address (the part that precedes the ‘@’ symbol in the e-mail address).

<domain> Domain name where the user’s message store resides.

<messageFile> Plain-text file that contains the auto-reply message to send for the vacation and reply modes.



��

The imservctrl command starts and stops servers on the local machine. Depending on the parameters included in calling it, imservctrl will either start, restart, or stop a single server, a list of servers, or all servers.

Syntax

imservctrl {start|stop|restart|drain|kill|exit|drainStart|killStart} [<server>...[<server>]]

Where:

Note: The imservctrl command will have no effect on a server that is not currently configured to run. A server is “configured to run” if the configuration key server_run has a value of “on.” Otherwise, the server is not configured to run. The <serv>_run configuration key is in the sysadmin configuration module. You can read this key either by running imconfedit and searching for this variable with your editor, or by running imconfget -h <hostname> -m sysadmin <serv>_run.

start Starts a configured server that is not currently running.

stop Stop a server that is configured and currently running.

restart Stops and starts a server that is configured and running.

drain Shuts down the servers without interrupting any current client connections

kill Shuts down the servers by issuing a UNIX kill -9 on the relevant process.

exit Same as stop.

drainStart Performs a drain and then starts the servers.

killStart Performs a kill and then starts the servers.

<server> Any one (or a list) of the following server processes: httpd, mta, mss, popserv, imapserv, immgrserv,

imconfserv, or imdirserv.



Example

To stop all servers on the local InterMail host, run imservctrl (from the $INTERMAIL/lib directory) as in the following example:

Note: Notice that in both stopping and starting the servers that there can be several Message Store processes running at the same time on the same machine. These processes are mss.1, mss.2, etc.

The server list is optional and when there is no list specified, imservctrl will act on all the servers configured to run on the current machine. To start a particular server and no others, you need to specify this particular server as the third parameter to imservctrl. For example, to start the POP server only, run imservctrl in the following manner:

��

The imservdisplay command displays information about InterMail servers. This command displays information from the time of the last server restart.

Syntax

imservdisplay

paris% imservctrl stopsbs-qasun3% imservctrl stopimservctrl: Warning: no httpd process foundimservctrl: stopping imapserv (648)imservctrl: stopping popserv (592)imservctrl: stopping mta (528)imservctrl: stopping mss.1 (462)imservctrl: stopping imdirserv (428)imservctrl: stopping immgrserv (397)imservctrl: stopping imconfserv (321)imservctrl: cleaning /imail/imail/tmp ...imservctrl: done

paris% imservctrl start popserv



Example

To view a report on server activity, run imservdisplay as in the following example:

The output from imservdisplay tells the user that servers are in operation and reports summarized information from log files.

��

The imservping command probes InterMail servers to see if they are running, checking to see if they are accessible through the network.

Note: The installation script creates the server configuration files, which reside in the config directory.

Syntax

imservping [-f <logFile>] [-v] [-h <host>] [<warnTimeout>] [<maxTimeout>] [<server>...[<server>]]

Where:

paris% imservdisplay

Monitoring InterMail modules: httpd imconfserv imdirserv immgrserv mss

......

imconfserv Report:------------------ Note: ProcFound: imconfserv process Found as PID: 9136. Note: ServerPing: imconfserv responded to version query ... /vol1/imail/log/imconfserv.log, Severity: Note { 6: ConfChangeAssessment 66: ConfClientConnect 3: ConfEndUpdate 6: ConfInstallSucceeded 21: ConfParmsPush 34: ConfPortConflict 15: ConfServerLock 3: ConfStartUpdate 4: ProcConfigChange......

-f <logFile> Name of the file to write imservping messages to (if there is no file name, output will go to standard output).

-v Verbose output.

-h <host> Host to check for all servers; alternately, use <server>.

<warnTimeout> Timeout period signal for the first probe (in seconds).

<maxTimeout> Timeout period signal for the second probe (in seconds).

<server> Name of server(s) to ping.



Note: If the name of the file is a full path name (that is, it begins with a slash ’/’), the system will use that name to create the file. Otherwise, it will create a log under the subdirectory “spool/logs” of the installation directory.

If a server is unavailable, imservping will report immediately; timeouts only apply when imservping is waiting for a response from an established connection.

Example

To check the status of all InterMail processes, run imservping as in the following example:

If the server does not respond during the <maxTimeout> time, an alarm message displays on the console. If all probed servers respond, imservping exits with a status of 0 (zero); otherwise, imservping will exit with a status equal to the number of unanswered probes (that is, non-responding servers).

Note that the server argument is optional: if it is absent, it will probe all configured servers (see imservctrl for information on servers and on how to check if a server is configured as “on”).

Note: The imservping command can run without timeout values (<warnTimeout> and <maxTimeout>). When it runs this way, imservping will report server status with a <warnTimeout> of 3 seconds and a <maxTimeout> of 6 seconds or report the server(s) as unreachable.

��(��

imservctrl calls the imservshutdown command when shutting servers down and we mention it here for completeness; however it is reserved for specific maintenance conditions and you should use it only in conjunction with your vendor or technical support.

��(��*

The imsmtpcheck command reports the state information about the SMTP port on the machine where the command runs. The output of this command goes to the imsmtpcheck.log file.

Syntax

imsmtpcheck

paris% imservping 1 5

Tue May 19 16:08:54 1998. imservping: (Info) mss/mss.1 respondedTue May 19 16:08:54 1998. imservping: (Info) imconfserv respondedTue May 19 16:08:54 1998. imservping: (Info) immgrserv respondedTue May 19 16:08:54 1998. imservping: (Info) imdirserv responded......



��

The imspoollistoldfiles command lists all spooled mail messages that are more than four days old. When the InterMail MTA receives mail, it may temporarily spool the mail in files beneath the queue directory. Files typically are not in the queue directory for more than a few seconds. It is possible that the MTA does not properly handle some files. These errors typically result in a piece of mail bouncing back to the originator. In some situations, it is possible that the MTA will never dispose of a message properly. The imspoollistoldfiles command identifies these files.

Note: If you want to change the “trigger age” from 4 days to some other number, you need to modify the imspoollistoldfiles script. Also, you cannot use this command before the 4th of a given month.

Syntax

imspoollistoldfiles [-days <number>] [-help]

Where:

��

The imsysmon utility performs a variety of checks in order to determine the operational state of InterMail. It identifies not only existing performance “warning” conditions in InterMail but also detects potential disturbances in the InterMail system as a whole.

Syntax

imsysmon [-c <cfgFilePath>][-h][-l <logFile>][-v][-version]

Where:

Note: For an example of how to configure and run imsysmon, please refer to the InterMail Kx Operations Guide.

-days <number> Find spool files older than <number> days. By default, imspoolistoldfiles will list spool files that are older than 4 days.

-help Print this help text.

-c <cfgFilePath> Path to the configuration file.

-h Prints usage statement.

-l <logFile> Prints output to specified log file.

-v Verbose mode.

-version Shows version information.


5InterMail C API

This chapter describes the C API library available for creating programs that access data in the Integrated Services Directory and InterMail MSS databases, and includes the following information:

• An overview of the semantics of the API library

• Descriptions of the data types used in the API

• Listing of individual API functions

• Description of compiling and linking applications with the API library

IntroductionData maintained by the Integrated Services Directory database, MSS database, and Configuration database can be accessed using an object-oriented C API. InterMail objects can be created, destroyed, read, and modified using this API. Using this library, it is possible to develop customized system administration commands, and to extend the features of InterMail while remaining compatible as InterMail is upgraded.

The InterMail Perl API described in Chapter 7 is based on this C library.

Note: You must have one of the recommended C/C ++ compilers for your specific UNIX platform to use the InterMail C API. If a suitable compiler is not available, consider using the InterMail Perl API instead.

Naming ConventionsTypes, functions, and constants in the InterMail C API are prefixed with IM_ to avoid conflicts and to make these types easy to identify. Header filenames use only lower case, and are prefixed with im_ instead. The library is named libim4.so.4.x.



Note: Due to the large set of software libraries (both InterMail and third party) accessed by the API, programs that link with the API may encounter other naming conflicts that are impossible to avoid.

Function SemanticsMost of the functions follow a consistent naming pattern:

• IM_InitX() initializes an object of type “X”, and must be called before that object is used in other functions.

• IM_FreeX() de-allocates the resources that are in use by an object of type “X”.

• IM_ReadX() reads information relevant to that type. For example, IM_ReadAccount() reads information about the account identified by the fields of an IM_Account object.

• IM_UpdateX() updates fields for an object of type “X”. If a char* field of that object contains a NULL pointer, this particular field is not updated. Numeric fields can also be set to a value that implies no change. All other fields containing data, except those that uniquely identify the object, are incorporated into the update operation.

• IM_CreateX() creates an object of type “X” in the Integrated Services Directory or MSS database using the data from the object’s fields.

• IM_DeleteX() deletes an object of type “X” from the Integrated Services Directory or MSS database.

Calling ConventionsWith few exceptions, the InterMail API calls operate on objects. These objects are represented using standard C structures that can be located on the stack, in the heap, or in global memory, depending on the caller’s preference and the requirements of the application.

All library functions return an integer value, with zero (IM_SUCCESS) indicating success, and non-zero indicating failure. Most functions, with the exception of IM_InitX() and IM_FreeX(), take an IM_Error* as their last argument. More detailed information about errors is returned in the IM_Error struct.

Library Initializationint IM_InitApplication(char* appName, IM_Error*);

This function must be called at least once before any other function in the library (except IM_InitX() functions or IM_InitLibrary()). If it returns a non-zero value, then the library was not properly initialized and no further calls to the library should be attempted.

InterMail C API


The appName argument will be used to control access to the InterMail configuration database, and to name the InterMail log file that may be created if errors occur in the application.

Calling this function more than once has no effect.

int IM_InitLibrary();

This is a simple wrapper around IM_InitApplication() that uses a generic appName value (“IM-C-API”). It is here for convenience and backward compatibility.

If you do not call either of these functions, the library will attempt to automatically initialize itself using IM_InitLibrary().

Object Data TypesEvery InterMail object’s structure begins with a header that allows the API to do run-time type verification and to detect improperly initialized objects.

The caller of the API need not worry about the contents of these headers; they are initialized using a function of the form IM_InitType(). Calling an API function with an object that has not been properly initialized will result in an error. When the caller is finished with an object, it is necessary to free the resources of that an object may have allocated using a function of the form IM_FreeType(). As a convenience, it is also possible to pass any properly initialized object to the function IM_Free(). Failure to pass objects to their IM_FreeType() function will result in memory leaks and poor performance. The Init and Free functions correspond roughly to constructors and destructors in C++.

All objects are passed by pointer, not by value; for example: IM_InitMbox(IM_Mbox*).

Some objects have a void* field called internalID following the header. Extra state related to the object is kept here to improve performance when accessing an object multiple times. This state is also deallocated, if necessary, by calling IM_FreeType().

Except for the header and internalID, most fields are of the type int and char*, and enum.

The following conventions must be observed by the caller when manipulating char* fields in these structures. The InterMail API guarantees that the same conventions are followed internally.

• All char* values must be allocated on the heap with malloc(), or a derivative like strdup().

• Any non-NULL char* value may be passed to free() or realloc() inside an API function.

• All non-NULL char* values will be passed to free() in the IM_Free function.

Callers are free to use char* values from an object, provided that they set that field to NULL before passing that object to another API function (particularly IM_Free).



Some functions require that one or more char* fields be set by the caller, and these conventions must be followed in such instances.

Overview of TypesThe types of objects supported by the InterMail API are:

The IM_Error and IM_StringArray types are general-purpose utility types.

The IM_Domain and IM_Account types are associated with the Integrated Services Directory. They control account provisioning, e-mail address aliases, and the routing of e-mail to forwarding addresses and the InterMail Message Store Server (MSS).

The IM_Mbox, IM_Folder, IM_Msg and IM_MimeInfo types are associated with the InterMail MSS. These objects control the delivery, removal, and organization of e-mail messages.

The IM_Reply type is associated with both the Integrated Services Directory and the InterMail MSS. This object controls the content and manner of automated replies to incoming mail for an account or a group of accounts.

IM_Error An error returned by an API function

IM_StringArray A collection of NULL-terminated strings

IM_Domain An e-mail domain; for example, my.company.com

IM_Account An account with associated attributes and a mailbox

IM_Mbox A mailbox belonging to an account, containing folders

IM_Folder A folder in a mailbox, organizing e-mail messages hierarchically

IM_Msg An e-mail message from a folder

IM_MimeInfo Information about the MIME (RFC 1521) structure of a message

IM_Reply An auto-reply message for an account

IM_Cos Class of service definition

IM_CosAttrDef Attribute referred to by one or more IM_Cos objects

InterMail C API


The IM_Cos types are associated with the Integrated Services Directory. These objects control the features of InterMail that are enabled for an account.

The IM_Config type stores information managed by the InterMail Configuration Server .

Errors Interface: im_error.h

typedef struct IM_Error{

IM_Header _header;int number;char* string;

} IM_Error;

When an error is encountered in an API function, the IM_Error object that was passed into the function is used to report the details of the error. The number field represents the type of error, and the string field contains details that may help in determining the source of the error. In some situations, and for all instances of some errors, the string field may be NULL.

Error numbers greater than 0xFFFF are two-part error codes. The high-order part refers to a category of errors and the low-order part determines the specific error within the category. These error codes can be converted to a short mnemonic string using IM_GetErrorMnemonic(). Other error numbers are related to improper use of the library and other miscellaneous problems. These errors are documented below.

enum IM_ErrorNumber { IM_ERROR_INVALID_ARG = -100, IM_ERROR_MALLOC, IM_ERROR_MISSING_ARG, IM_ERROR_MISSING_ATTR, IM_ERROR_DEAD_DATA, IM_ERROR_NOT_FOUND, IM_ERROR_ACCOUNT_COS, /* invalid account COS */ IM_ERROR_NUMBER_NOT_IN_USE = 0, IM_DIR_GENERIC_ERROR = 2000, IM_DIR_INTERNAL_ERROR, /* unknown internal error */ IM_DIR_BAD_DOMAIN,

IM_CosAttrDefArray Collection of IM_CosAttrDef objects

IM_Config Structure to hold configuration data from the configuration database.

IM_LogContext Context used when generating log messages

IM_LogMsg A log file entry



IM_DIR_BAD_SMTP, IM_DIR_BAD_ALIAS, IM_DIR_BAD_POP, IM_DIR_BAD_PASSWORD, IM_DIR_BAD_ALIAS_DOMAIN, IM_DIR_DUP_POP, /* duplicate pop address*/ IM_DIR_DUP_DOMAIN, /* duplicate domain */ IM_DIR_DUP_SMTP_ALIAS, /* duplicate smtp alias */ IM_DIR_DUP_SMTP_OR_INT_ID, /* duplicate pSmtp or Int Id */ IM_DIR_CANT_DELETE_PSMTP, /* can’t delete primary smtp */ IM_DIR_BAD_SCHEMA, /* tables & package are incompatible */ IM_DIR_NO_FORWARDS, /* can’t set forwarding if no forwards */ IM_EXISTS, /* object to be created already exists */ IM_NOT_ALLOWED /* operation is not allowed */};

The functions below manipulate the IM_Error structure.

int IM_InitError(IM_Error* error);int IM_FreeError(IM_Error* error);int IM_SetError(IM_Error* error, int number, const char* string);int IM_GetErrorMnemonic(const IM_Error* error, char* buf, int bufsize);int IM_Errno2Mnemonic(int errnum, char* buf, int bufsize)

Before passing an IM_Error structure to an API function, it must be initialized with IM_InitError().

After handling an error reported by an API function, the object resources of IM_Error should be released using IM_FreeError().

The IM_SetError() function fills the IM_Error object’s fields, copying the string into a newly allocated buffer. Most users will never need to call IM_SetError() directly.

The IM_GetErrorMnemonic() function fills in the buf argument with a short textual representation of the number in the IM_Error argument. For example, 0x320004 (3,276,804) is converted to AcctNoSuchUser. The bufsize argument indicates the size of the storage available in buf. A buffer size of 64 bytes is sufficient to hold any mnemonic string.

IM_Errno2Mnemonic() works the same way as IM_GetErrorMnemonic(), but it accepts the number from an IM_Error object.

InterMail C API


String ArraysInterface: im_stringarray.h

typedef struct IM_StringArray{ IM_Header _header; int num; char** strings;} IM_StringArray;

int IM_InitStringArray(IM_StringArray*);int IM_FreeStringArray(IM_StringArray*);int IM_ZeroStringArray(IM_StringArray*);int IM_CopyStringArray(IM_StringArray* dst, const IM_StringArray* src);

DomainsInterface: im_domain.h

typedef enum IM_DomainType{ IM_DOMAIN_ NO_CHANGE=-1, IM_DOMAIN_UNKNOWN=0, IM_DOMAIN_DELETED = ’D’, IM_DOMAIN_LOCAL = ’L’, IM_DOMAIN_NON_AUTH = ’N’, IM_DOMAIN_REWRITE= ’R’} IM_DomainType;

The information about domains is conveyed via the structure IM_Domain:

typedef struct IM_Domain{

IM_Header _header;IM_DomainType type;char* name;char* relayHost;char* rewriteName;

char* wildcardAccount;} IM_Domain;

The fields of this structure and their syntax are described below:

_header Internal use.

type The type of the domain; see IM_DomainType.

name The name of the domain. Can be any valid domain name up to 64 characters long.



The functions below manipulate the IM_Domain structure:

int IM_InitDomain(IM_Domain* domain);int IM_FreeDomain(IM_Domain* domain);int IM_CopyDomain(IM_Domain* target, const IM_Domain* origin);

The functions below access and modify information in the InterMail Directory through the IM_Domain structure:

int IM_ReadDomain (IM_Domain* domain, IM_Error* error);int IM_CreateDomain(IM_Domain* domain, IM_Error* error);int IM_DeleteDomain(IM_Domain* domain, IM_Error* error);int IM_UpdateDomain(IM_Domain* domain, IM_Error* error);int IM_ReadDomains(char* from, char* till, int max, IM_StringArray* domains, IM_Error* error);int IM_ReadSubDomains(char* topDomain, char* from, char* till, int max, IM_StringArray* domains, IM_Error* error);

��&��)��

int IM_ReadDomain (IM_Domain* domain, IM_Error* error);

The name field of the domain argument must point to the name of an SMTP domain, e.g., my.company.com. The function returns an error if the specified domain does not exist in the Directory database. The type field is set according to the type of the domain, and other fields are set depending on the type.

��'��)��

int IM_CreateDomain(IM_Domain* domain, IM_Error* error);

The name field of the domain argument must point to the name of an SMTP domain. The type field of the domain argument must be a valid type for domain creation,

relayHost Host name to use for SMTP relay for non-authoritative domains. May be specified as <host>.<domain>, for a total length of (32 + 1 + 64 = 97). Used with domains of type IM_DOMAIN_NON_AUTH only.

rewriteName Change the domain portion of the destination address of all mail received by ‘name’ domain to ‘rewriteName’ domain. Can be any valid domain name up to 64 characters long. Used with domains of type IM_DOMAIN_REWRITE only.

wildcardAccount Account within the name domain to use as the destination mailbox for unknown recipients. Can be any valid account name up to 64 characters long. Used with domains of type IM_DOMAIN_LOCAL only. You can only use this field for an update, it will fail if it has any value during creation.

InterMail C API


either IM_DOMAIN_LOCAL, IM_DOMAIN_REWRITE, or IM_DOMAIN_NON_AUTH. This function creates the specified domain in the Directory database.

Three of the parameters in IM_Domain are individually used with three different domain types. relayHost must be specified with domain type IM_DOMAIN_NON_AUTH. rewriteName must be specified with domain type IM_DOMAIN_REWRITE. The relayHost and rewriteName parameters cause an error if specified with an incorrect domain type. wildcardAccount is used with domain type IM_DOMAIN_LOCAL, but will cause an error on domain creation because the domain must first be created before any accounts within the domain (including the wildcard account) can be created. After the domain is created and the account is created, the wildcard account can be specified using IM_UpdateDomain.

��)��)��

int IM_DeleteDomain(IM_Domain* domain, IM_Error* error);

The name field of the domain argument must point to the name of an SMTP domain. This function changes the domain type of the specified domain to IM_DOMAIN_DELETED in the Directory database.

��-��)��

int IM_UpdateDomain(IM_Domain* domain, IM_Error* error);

The name field of the domain argument must point to the name of an SMTP domain and the type field must be IM_DOMAIN_DELETED, IM_DOMAIN_LOCAL, IM_DOMAIN_REWRITE, or IM_DOMAIN_NON_AUTH. This function changes the domain type, relayHost, rewriteName, and/or wildcardAccount of the specified domain as dictated by the values in the domain argument. Possible uses of IM_UpdateDomain are to:

• Delete a domain

• Change or add a wildcard account to a local domain

• Change a relay host for a non-authoritative domain

• Change a rewrite domain

• Change a domain type from non-authoritative to local

As with IM_CreateDomain, three of the parameters in IM_Domain are individually used with three different domain types. relayHost must be specified if updating to domain type IM_DOMAIN_NON_AUTH. rewriteName must be specified if updating to domain type IM_DOMAIN_REWRITE. wildcardAccount may optionally be specified if updating to domain type IM_DOMAIN_LOCAL. The relayHost, rewriteName, and wildcardAccount parameters are ignored if specified with incorrect domain types.

There are some limits on changing domain types using IM_UpdateDomain. Setting any domain to type deleted is a valid operation, however consistency checking may



show account or rewrite domain dependencies that force other changes before the delete operation will be successful. Setting a deleted domain to any other domain type is a valid operation, provided any required parameters are included and valid. Switching a domain from local to non-authoritative (or visa-versa) is also valid. However, switching a domain from local or non-authoritative to rewrite (or visa-versa) is not allowed at this time. Delete the domain first, then set the domain to the desired type.

Note: When IM_UpdateDomain specifies a wildcard account, the user must use only the local portion of the SMTP address.

��&��)��

int IM_ReadDomains(char* from, char* till, int max, IM_StringArray*, IM_Error*);

Fetch the domain names defined in the InterMail database. The from and till arguments specify the lower and upper bounds of the range of names to return, where from is inclusive, till is exclusive. If either from or till is NULL, it defaults to the lexically-lowest or lexically-greatest domain name, respectively. If the value of max is –1, then all matching domains are returned, otherwise no more than max names are returned.

It is possible to iterate through all domains in the Directory by repeatedly calling IM_ReadDomains() and passing NULL for the till argument, and the last domain name from the previous invocation as the from argument. Since the from argument is inclusive, it is necessary to skip the first domain in the results on the second and subsequent invocations.

On success, the results are stored in the IM_StringArray argument.

��&��)��

int IM_ReadSubDomains(char* topDomain, char* from, char* till, int max, IM_StringArray*, IM_Error*);

Fetch the subset of the domain names defined in the InterMail database that are contained by topDomain, e.g. if topDomain is software.com, then this function will return domains like east.software.com and sales.west.software.com, but not hardware.com. The from and till arguments specify the lower and upper bounds of the range of names to return, where both from and till are exclusive (note the difference from IM_ReadDomains(), above). If either from or till is NULL, it defaults to the lexically-lowest or lexically-greatest domain name, respectively. If topDomain is NULL, all domains are matched. No more than max names are returned, and max must be greater than zero.

Starting with NULL from and till arguments, it is possible to iterate through all sub-domains of a specified domain by repeatedly calling IM_ReadSubDomains() and passing NULL for the till argument, and the last domain name from the

InterMail C API


previous invocation as the from argument. Since from is exclusive, there is no need to skip any values in the results.

On success, the results are stored in the IM_StringArray argument. If the same IM_StringArray object is used repeatedly, the strings it points to will be de-allocated and re-initialized each time IM_ReadSubDomains() is called.

AccountsInterface: im_account.h

typedef enum IM_AcStatus{ IM_ACSTATUS_NO_CHANGE=-1, /* Used to imply no change desired */ IM_ACSTATUS_UNKNOWN=0,

IM_ACSTATUS_ACTIVE, /* Active */ IM_ACSTATUS_SUSPENDED, /* Suspended */ IM_ACSTATUS_DELETED, /* Deleted */ IM_ACSTATUS_MAINTENANCE, /* Maintenance mode */ IM_ACSTATUS_LOCKED, /* Locked mode */ IM_ACSTATUS_PROXY /* Used for account migration */} IM_AcStatus;

typedef enum IM_PwHashType{ IM_PWHASH_NO_CHANGE=-1, /* Used to imply no change desired */ IM_HASH_UNKNOWN=0, IM_PWHASH_CLEAR, /* No hash scheme */ IM_PWHASH_MD5_PO, /* MD5 hash scheme (proprietary extensions) */ IM_PWHASH_UNIX /* UNIX crypt() style hashing */} IM_PwHashType;

typedef enum IM_LocalDelivery{ IM_DELIVERY_NO_CHANGE=-1, /* Used to imply no change desired */ IM_DELIVERY_UNKNOWN=0, IM_DELIVERY_ENABLED, /* Delivery to account mailbox enabled */ IM_DELIVERY_DISABLED /* Delivery to account mailbox disabled */} IM_LocalDelivery;

typedef enum IM_ForwardFlag{ IM_FORWARDING_NO_CHANGE=-1, /* Implies no change desired */ IM_FORWARDING_UNKNOWN=0,



IM_FORWARDING_ENABLED, /* forwarding is enabled. */ IM_FORWARDING_DISABLED /* forwarding is disabled. */} IM_ForwardFlag;

typedef enum IM_ReplyType{ IM_REPLY_NO_CHANGE=-1, /* Implies no change desired */ IM_REPLY_UNKNOWN=0, IM_REPLY_NONE= ’N’, /* No auto-reply mode is engaged. IM_REPLY_AUTO= ’R’, See InterMail documentation for */ IM_REPLY_ECHO= ’E’, a detailed description of */ IM_REPLY_VACATION= ’V’ the reply modes. */} IM_ReplyType;

typedef struct IM_Account{ IM_Header _header; void* _internalID; char* smtpAddress; char* popAddress; char* mssHost; char* smtpHost; char* popHost; char* emailIntID; char* password; char* plainPassword; char* cosName; IM_ServiceDef acCos; IM_ServiceDef resultCos; IM_PwHashType hash; IM_LocalDelivery local; IM_ForwardFlag forward; IM_ReplyType reply; IM_AcStatus status; } IM_Account;

The fields of this structure and their syntax are :


_internalID Internal use.

smtpAddress SMTP address, two strings up to 64 characters each, separated by an “@” symbol. The first string is the “local” portion of the address. The second string must be a domain name known to the InterMail Directory.

popAddress Login name for POP, IMAP, and InterManager, up to 129 characters.

InterMail C API


These functions manipulate the IM_Account structure:

int IM_InitAccount(IM_Account* account);int IM_FreeAccount(IM_Account* account);

Note: IM_InitAccount() must be called before attempting to use any function which uses IM_Account.

mssHost Hostname of up to 32 characters. Must correspond to the “logical hostname” of a system running an InterMail MSS. This field must be NULL if status is IM_ACSTATUS_PROXY.

smtpHost Hostname of up to 64 characters, used when an account is in proxy mode to forward SMTP requests to an alternate server. This field must be NULL if status is not IM_ACSTATUS_PROXY.

popHost Hostname of up to 64 characters, used when an account is in proxy mode to forward POP requests to an alternate server. This field must be NULL if status is not IM_ACSTATUS_PROXY.

emailIntID Number with up to 38 decimal digits represented as a string

status Status of the account; see IM_AcStatus.

local Local delivery option; see IM_LocalDelivery.

cosName COS name to which the account subscribes.

acCos Account specific COS preferences (may not correspond to the actual COS for the account, see resultCos).

resultCos Resultant COS after applying overriding rules on the subscribed COS attributes and the account specific COS preferences

hash Type of password hashing scheme used, see IM_PwHashType.

password Encrypted password

plainPassword Unencrypted password

forward Whether forwarding is enabled for the account, see IM_ForwardFlag.

reply Auto-reply mode for the account, see IM_ReplyType.



The following functions use the information in IM_Account to access or change the information in the Directory:

int IM_CreateAccount(IM_Account*, IM_Error*); int IM_UpdateAccount(IM_Account*, IM_Error*);int IM_UpdateAccountAddr(IM_Account*, IM_Account*, IM_Error*);int IM_DeleteAccount(IM_Account*, IM_Error*);int IM_ReadAccount(IM_Account*, IM_Error*);

int IM_CreateAlias(IM_Account* smtp, const char* alias, IM_Error*);int IM_DeleteAlias(const char* alias, IM_Error*);int IM_ReadAccountAliases(IM_Account*, IM_StringArray*, IM_Error*);int IM_ReadAlias(const char* alias, IM_Account*, IM_Error*);int IM_ReadPOP3(const char* pop3, IM_Account*, IM_Error*);

int IM_CreateForward(IM_Account* from, const char* smtpTo, IM_Error*);int IM_DeleteForward(IM_Account* from, const char* smtpTo, IM_Error*);int IM_ReadAccountForwards(IM_Account*, IM_StringArray*, IM_Error*);int IM_EnableAccountForwards(IM_Account* account, IM_Error* error);int IM_DisableAccountForwards(IM_Account* account, IM_Error* error);

int IM_HashPassword(char* password, char* hashPassword, int len, IM_PwHashType);int IM_CheckPassword(char* password, char* hashPassword, IM_PwHashType);

int IM_ResetAcCos(IM_Account*, IM_Error*);int IM_UpdateAcCos(IM_Account*, char* name, char* value, IM_Error*);int IM_DeleteAcCos(IM_Account*, char* name, IM_Error*);

int IM_ReadAccounts(char* domain, char* from, char* till, int max, IM_StringArray* addresses, IM_Error*);

��'��,��

int IM_CreateAccount(IM_Account*, IM_Error*);

This function creates an account in the Directory database with the information in the IM_Account argument. The following fields are used:

smtpAddress Required

mssHost Required (if account status is not IM_ACSTATUS_PROXY)

InterMail C API


Note on COS values

The C-API supports a logical overlap between some fields in the IM_Account structure and corresponding key-value pairs in an account’s COS settings. After a successful call to IM_ReadAccount(), the local-delivery (account->local), forwarding (account->forward), and reply-mode (account->reply) values can also be read from resultCos field using the COS attribute names: pref_localdelivery, pref_forwarding, and pref_replymode. As with other COS attributes, all values are stored as strings. pref_localdelivery and pref_forwarding are Boolean, so their values will be either ″1″ or ″0″. pref_replymode will use one of the characters from IM_ReplyType.

smtpHost Required (if account status is IM_ACSTATUS_PROXY)

popHost Required (if account status is IM_ACSTATUS_PROXY)

emailIntID Required

status Optional – defaults to IM_ACSTATUS_ACTIVE

popAddress Optional – defaults to the local portion of smtpAddress.

local Optional – local delivery is enabled by default.

cosName Optional – defaults to the “default” COS, not recommended.

acCos Optional – no account-specific COS attributes are set by default. See the helper functions IM_ResetAcCos(), IM_UpdateAcCos(), and IM_DeleteAcCos() below.

hash Optional – defaults to IM_PWHASH_CLEAR.

plainPassword

password

Optional – if plainPassword is set it is assumed to be the clear text version of the password. The password will be encrypted according to the hash field when it is stored in the Directory. Otherwise, if password is set, it is assumed to be the encrypted version of the password as determined by hash.

When the plainPassword parameter is specified, and the hash function is set to something other than "clear", the input password is encrypted in the client before it is sent to the Directory.

If neither password field is specified, the account will have no password and the account’s user will be unable to access any service requiring authentication, e.g. POP, IMAP, or InterManager. The password may be specified later using IM_UpdateAccount().



For IM_CreateAccount(), pref_localdelivery can be specified in the acCos field for a new account. For IM_UpdateAccount(), both pref_localdelivery and pref_forwarding can be updated using attributes in the acCos field. In both functions, attributes specified in acCos take precedence over the corresponding fields in the IM_Account structure.

The pref_replymode setting cannot be altered using the acCos field since this feature generally requires more information than a simple mode value. Use the functions IM_CreateReply(), IM_UpdateReply(),and IM_DeleteReply()instead.

Note: The IM_CreateAccount function returns an error when an account is created with a PWHASH value of IM_PWHASH_NO_CHANGE. The IM_PWHASH_NO_CHANGE constant is only valid when used with IM_UpdateAccount().

��-��,��

int IM_UpdateAccount(IM_Account*, IM_Error*);

This function updates account information in the database. The account argument must have the smtpAddress field defined, as this determines which account will be updated. Other fields can be set in order to change their values for the account in the Directory. To leave a field unchanged, set the field to NULL for string (char*) values, or to an appropriate NO_CHANGE enumeration value. Often it is best to start with a freshly initialized IM_Account structure when performing updates so that no fields are inadvertently set.

If the password or plainPassword field is set, they each obey the same semantics as in IM_CreateAccount().When the plainPassword parameter is specified in IM_UpdateAccount() and the hash function is set to something other than clear, the input password is encrypted in the client before it is sent to the Directory.

The resultCos field cannot be updated.

To add or modify per-account COS attributes, set the attribute names and their desired values in the acCos field. To delete a per-account attribute, set the name of the attribute in acCos, but leave the value NULL. See the helper functions IM_ResetAcCos(), IM_UpdateAcCos(), and IM_DeleteAcCos() below.

��"��(��

int IM_HashPassword(char* password, char* hashPassword, int len, IM_PwHashType);

Take the contents of the password and encrypt it according to the specified IM_PwHashType. Store the results in hashPassword, which is assumed to be large enough to hold at least len bytes. If hashPassword is not large enough to hold the

InterMail C API


result, an error is returned. A hashPassword size of 64 should be sufficient for most purposes.

Note: It is not necessary to use this function with IM_CreateAccount(). If the hash field of an IM_Account is set, the plainPassword will be encrypted appropriately while creating the account. In addition, due to the way passwords are hashed, the same clear text password submitted twice may not result in the same hashed password output.

��'(��*��

int IM_CheckPassword(char* password, char* hashPassword, IM_PwHashType);

Validates password using hashPassword and IM_PwHashType fetched from the InterMail directory via IM_ReadAccount(). The function returns IM_SUCCESS if the password matches, otherwise IM_FAILURE.

Note: IM_ReadAccount() provides a more complete authentication capability when the caller sets the plainPassword field in the IM_Account argument.

��&��,�'��

int IM_ResetAcCos(IM_Account*, IM_Error*);

Clear all the values in the acCos field of an IM_Account. All associated string storage is freed.

This function has no effect on the account in the Integrated Services Directory; only the information stored locally in the IM_Account structure is modified.

To commit these changes to the ISD, call the IM_UpdateAccount function subsequently.

��-��,�'��

int IM_UpdateAcCos(IM_Account*, char* name, char* value, IM_Error*);

Insert or change the value of an attribute in the acCos field of an IM_Account. String storage associated with the previous value, if any, is freed. The name argument should not use any upper-case characters.

This function has no effect on the account in the Integrated Services Directory, only the information stored locally in the IM_Account structure is modified.




��)��,�'��

int IM_DeleteAcCos(IM_Account*, char* name, IM_Error*);

Remove a single value from the acCos field of an IM_Account. The name argument should not use any upper-case characters.

This function has no effect on the account in the Integrated Services Directory, only the information stored locally in the IM_Account structure is modified.


��-��,��,��

int IM_UpdateAccountAddr(IM_Account* old, IM_Account* new, IM_Error*);

This function updates the smtpAddress field of an account, which is not possible with IM_UpdateAccount(). The smtpAddress field of the first IM_Account argument (old) specifies the account whose address is to be changed. The second IM_Account argument (new) specifies the desired smtpAddress.

��)��,��

int IM_DeleteAccount(IM_Account*, IM_Error*);

This function deletes the account from the Directory database. The account argument must contain the smtpAddress field to uniquely identify the account to be deleted.

Note: IM_DeleteAccount only deletes the account information from the database. This is not the same as removing a mailbox. In order to delete a mailbox, you must use the IM_DeleteMbox API.

��&��,��

int IM_ReadAccount(IM_Account*, IM_Error*);

This function fills in the account argument with information from the database. The account argument must specify one of the following fields to identify the account to be read: smtpAddress, popAddress, or emailIntId. If more than one of these fields is set, the API uses the first one it finds in the ordering listed here.

When reading account information, regardless of what hash type is specified in an account, IM_ReadAccount() sends the input "plain text" password unaltered to the Directory (similar to the operation of a typical POP client).

If the plainPassword field is set, then the function call is treated as a request for authentication. Under these circumstances, IM_ReadAccount() will return an IM_DIR_BAD_PASSWORD error if the password does not match the (possibly

InterMail C API


encrypted) copy in the account, or IM_DIR_GENERIC_ERROR error if the account is in a state that does not allow user-level access.

��&��,��

int IM_ReadAlias(const char* alias, IM_Account*, IM_Error*);

This function looks up an account using an e-mail alias. If an account is found, the account object is filled in just like IM_ReadAccount().

��&��/�6

int IM_ReadPOP3(const char* pop3, IM_Account*, IM_Error*);

This function looks up an account using a POP login name. If an account is found, the account object is filled in just like IM_ReadAccount().

��'��,��

int IM_CreateAlias(IM_Account* smtp, const char* alias, IM_Error*);

This function creates an alias for the account identified by the smtp argument. This argument must contain the smtpAddress field to uniquely identify the account. The alias argument must contain a fully qualified smtpAddress to be used as the alias to this account.

��)��,��

int IM_DeleteAlias(const char* alias, IM_Error*);

This function deletes an alias identified by the alias argument.

��&��,��,��

int IM_ReadAccountAliases(IM_Account*, IM_StringArray*, IM_Error*);

This function reads all the aliases corresponding to an account in the database identified by the account argument. The account argument must contain the smtpAddress field to uniquely identify the account whose forwards have to be read. The forwards are returned in the IM_StringArray argument.

��'��

int IM_CreateForward(IM_Account* from, const char* smtpTo, IM_Error*);

This function creates a forwarding address for mail destined for an account. The from argument must contain the smtpAddress field filled in to uniquely identify the account. The smtpTo field identifies a forwarding address that is the destination.



��)��

int IM_DeleteForward(IM_Account* from, const char* smtpTo, IM_Error*);

This function deletes a forwarding association between the account identified by the from argument and the forward address identified by the smtpTo argument. The from account type must contain the smtpAddress field to uniquely identify the account.

��&��,��

int IM_ReadAccountForwards(IM_Account*, IM_StringArray*, IM_Error*);

This function reads all the forwarded addresses corresponding to an account. The account argument must have the smtpAddress filled in to uniquely identify the account. The IM_StringArray argument contains the forwarded addresses upon return.

�� ,��

int IM_EnableAccountForwards(IM_Account*, IM_Error* error);

This function enables forwarding for an account identified by the IM_Account argument. The smtpAddress of this argument must be filled in to uniquely identify the account.

��)��,��

int IM_DisableAccountForwards(IM_Account*, IM_Error*);

This function disables forwarding for an account identified by the IM_Account argument. The smtpAddress of this argument must be filled in to uniquely identify the account.

��&��,��

int IM_ReadAccounts(char* domain, char* from, char* till, int max, IM_StringArray* addresses, IM_Error*);

Fetch the subset of SMTP addresses defined in the InterMail Directory that are in domain. For example, if the following accounts exist: jack@ software.com, [email protected], [email protected], and [email protected], then this function will return jack and jill if the domain argument is software.com.

The from and till arguments specify the lower and upper bounds of the range of addresses to return, where from and till are both exclusive (like IM_ReadSubDomains(), note the difference from IM_ReadDomains(), above). If

InterMail C API


either from or till is NULL, it defaults to the lexically-lowest or lexically-greatest address, respectively. The domain argument must be specified. No more than max names are returned, and max must be greater than zero.

Starting with NULL values for the from and till arguments, it is possible to iterate through all addresses in a domain by repeatedly calling IM_ReadAccounts() and passing NULL for the till argument, and the last address from the previous invocation as the from argument. Since from is exclusive, there is no need to skip any values in the results.

On success, the results are stored in the IM_StringArray argument. If the same IM_StringArray object is used repeatedly, the strings it points to will be de-allocated and re-initialized each time IM_ReadAccounts() is called.

Mailboxes Interface: im_mbox.h

typedef struct IM_Mbox { IM_Header _header; void* _internalID; char* host; char* name; /* String decimal digits, same as emailIntID */ int msgsStored; int bytesStored; char* inbox;} IM_Mbox;

int IM_InitMbox (IM_Mbox*);int IM_FreeMbox (IM_Mbox*);

int IM_ReadMbox (IM_Mbox*, IM_Error*);int IM_CreateMbox(IM_Mbox*, const char* welcomeMsgId, IM_Error*);int IM_DeleteMbox(IM_Mbox*, IM_Error*);int IM_SetMSSConnPoolSize(int size, IM_Error *);

��&��!

int IM_ReadMbox(IM_Mbox*, IM_Error*);

Fetch information about an existing mailbox.

The caller must set the host and name fields of the IM_Mbox argument.



��'��!

int IM_CreateMbox(IM_Account*, const char* welcomeMsgId, IM_Mbox*, IM_Error*);

Create a new mailbox using fields from the IM_Account argument and the welcome message-ID. The IM_Account’s mssHost and emailIntID fields must have non-NULL values, and the IM_Account quota fields must be set appropriately. Normally, this should be done by calling IM_ReadAccount(), although in some special circumstances it is reasonable to assign these fields directly.

The welcomeMsgId parameter specifies the Message ID of a message stored in the database that the user would like to be automatically inserted into the newly created mailbox (i.e. this message usually introduces the user to the system and usage policies). If the welcome message-ID is NULL or none, no welcome message will be inserted into the mailbox.

On success, the IM_Mbox argument will be initialized with the newly created mailbox information.

��)��!

int IM_DeleteMbox(IM_Mbox*, IM_Error*);

Deletes a mailbox.

The caller must set the host and name fields of the IM_Mbox argument.

��'��0�

int IM_SetMSSConnPoolSize(int size, IM_Error *);

This function sets the size of the MSS connection pool. The default size is 0, meaning no caching is done. If the connection pool size is set to n, then the last n connections made to an MSS will be cached.

When using an IM_Mbox, if the C-API needs to make a connection to an MSS, it will check its connection pool first to see if there is an existing connection available. If there is, it will use it, otherwise it will make a new one.

When an IM_Mbox is destroyed, the MSS connection associated with it (if any) is placed in the pool, unless that would cause the size of the pool to exceed the maximum specified by this function, in which case the connection is destroyed.

InterMail C API


Folders Interface: im_folder.h

typedef enum IM_MsgFlagsIndex { IM_MSGFLAG_RECENT=0, IM_MSGFLAG_SEEN, IM_MSGFLAG_ANSWERED, IM_MSGFLAG_FLAGGED, IM_MSGFLAG_DRAFT, IM_MSGFLAG_DELETED} IM_MsgFlagsIndex;

typedef struct IM_Folder{ IM_Header _header; void* _internalID; char* pathname; int numFolders; int readOnly; int clearRecent; char** names; int numMsgs; int UIDValidity; int* msgRefs; int* msgUIDs; int* msgSizes; char** msgIds; char** msgFlags;} IM_Folder;

The fields of this structure and their syntax are described below:



pathname Location of the folder within the mailbox.

numFolders Number of sub-folders contained by this folder.

names Names of the sub-folders contained by this folder.

numMsgs Number of messages in this folder, also the size of the arrays pointed to by msgRefs, msgUIDs, msgSizes, msgIds, and msgFlags.

msgRefs Internal index for each message in this folder, required to use IM_Message.



int IM_InitFolder (IM_Folder*);int IM_FreeFolder (IM_Folder*);

int IM_ReadFolder (IM_Mbox*, IM_Folder*, IM_Error*);int IM_CreateFolder(IM_Mbox*, IM_Folder*, IM_Error*);int IM_DeleteFolder(IM_Mbox*, IM_Folder*, IM_Error*);int IM_RenameFolder(IM_Mbox*, IM_Folder*, const char* dstname, IM_Error*);int IM_DeleteFolderMsgs(IM_Mbox*, IM_Folder*, int count, int* msgArray, IM_Error*);int IM_ScanFolderMsgs(IM_Mbox*, IM_Folder*, int count, IM_Msg** msgArray, IM_Error*);int IM_MoveMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int count, int* msgRef, IM_Error*);int IM_CopyMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int count, int* msgRef, IM_Error*);

To read, create, rename, or delete a folder, the caller must initialize an IM_Mbox object as described above, and also set the IM_Folder::pathname field.

IM_ReadFolder() will fill in all remaining fields except clearRecent. The information in these fields is necessary in order to navigate to sub-folders or to access messages in the folder. In particular, values from the msgRefs array must be used to initialize an IM_Message object.

msgUIDs IMAP UID’s for each message in this folder. All the UID’s will be zero if connected to an older InterMail MSS without IMAP support.

msgSizes Size in bytes of each message in this folder.

msgIds POP UIDL strings for each message in this folder.

msgFlags IMAP message flags for the messages in this folder. Each flag string currently contains six characters, each a T or an F. Each location in the array is identified by a constant in enum IM_MsgFlagsIndex.

clearRecent Specifies whether the recent flags should be cleared when doing an IM_ReadFolder (default: FALSE)

UIDValidity Read-only field returned by IM_ReadFolder; this is the UIDVALIDITY value from IMAP.

readOnly Read-only field returned by IM_ReadFolder. Set to FALSE if a POP client has the folder open, in which case the caller should not make changes to the folder. This is also present in the Folder object of the Perl API.

InterMail C API


��&��

int IM_ReadFolder(IM_Mbox*, IM_Folder*, IM_Error*);

Fetch information about a folder.

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument.

��'��

int IM_CreateFolder(IM_Mbox*, IM_Folder*, IM_Error*);

Create a new folder in a mailbox.


��)��

int IM_DeleteFolder(IM_Mbox*, IM_Folder*, IM_Error*);

Delete a folder from a mailbox.


��&��

int IM_RenameFolder(IM_Mbox*, IM_Folder*, const char* dstname, IM_Error*);

Renames the specified folder.

��)��

int IM_DeleteFolderMsgs(IM_Mbox*, IM_Folder*, int count, int* msgArray, IM_Error*);

Deletes ones or more messages from a folder. The caller must set the host and name fields on the IM_Mbox argument, and the pathname field of the IM_Folder argument. msgArray is an array of integers; the length of this array is given by the count argument. The integers specify a list of message indices to delete (0 being the first message in the folder). Normally IM_ReadFolder would be called first so the caller can select which messages to delete. Using this function is more efficient than deleting the messages one by one.

Note: This function was formerly called IM_DeleteFolderMessages, and this name is still supported for backward compatibility.



��

int IM_ScanFolderMsgs(IM_Mbox*, IM_Folder*, int count, IM_Msg** msgArray, IM_Error*);

Scans the headers of one or more messages in a folder, so that future calls to IM_ReadMsgHeader() will be faster. The call must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument. msgArray is an array of pointers to IM_Msg objects; the length of this array is given by the count argument. Normally IM_ReadFolder() would be called first so the caller can select which messages to scan. This function is useful when the caller needs to look at the headers of a large number of messages; it is more efficient to load the headers with this one call than to have them loaded one by one.

Note: This function was formerly called IM_ScanFolderMessages, and this name is still supported for backward compatibility.

��

int IM_MoveMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int count, int* msgRef, IM_Error*);

Move count messages specified by the msgRef array from the src folder to the dst folder.

��'��

int IM_CopyMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int count, int* msgRef, IM_Error*);

Copy count messages specified by the msgRef array from the src folder to the dst folder.

Messages Interface: im_msg.h

typedef struct IM_Msg{ IM_Header _header; void* _internalID; int msgRef; int seen; int size; char* msgId; time_t arrivalTime; char* arrivalTimeString; char* bodyBuffer;} IM_Msg;

InterMail C API


/* Caller must set IM_Msg::msgRef. */int IM_InitMsg (IM_Msg*);int IM_FreeMsg (IM_Msg*);

int IM_ReadMsg (IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);int IM_CreateMsg(IM_Mbox*, IM_Folder*, const char* from, cons char* text, IM_Msg*, IM_Error*);int IM_DeleteMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);int IM_ReadMsgHeader(IM_Mbox*, IM_Folder*, IM_Msg*, const char* hdrLabel, char** hdrValue, IM_Error*);int IM_ReadMsgBody(IM_Mbox*, IM_Folder*, IM_Msg*,int offset, int size, char** text, IM_Error*);int IM_UpdateMsgFlags(IM_Mbox*, IM_Folder*, IM_Msg*, const char* flags, IM_Error*);

��&��

int IM_ReadMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);

Fetch information about a message.

This function will fill in all remaining fields in the IM_Msg object, but that does not include any of the actual message contents. To search for and retrieve specific headers from the message, call IM_ReadMsgHeader(). To retrieve all or part of the message text, call IM_ReadMsgBody().

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument.

��'��

int IM_CreateMsg(IM_Mbox*, IM_Folder*, const char* from, const char* text, IM_Msg*, IM_Error*);

Create a new message in a folder.

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument. The from argument is used in the message “envelope”. The text argument should point to the full text of an RFC822-formatted message, including headers. No syntax checking is performed on this text. On success, the msgRef field of the IM_Msg argument will be set.

��)��

int IM_DeleteMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);

Delete a message from a folder.

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument.



��&��"��

int IM_ReadMsgHeader(IM_Mbox*, IM_Folder*, IM_Msg*, const char* hdrLabel, char** hdrValue, IM_Error*);

Fetch the value of a header from a message.

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument. The hdrLabel argument should point to the name of a header field, e.g. From:. On success, *hdrValue will point to a newly malloc’ed buffer containing the value of the header as a null-terminated string.

��&��.��

int IM_ReadMsgBody(IM_Mbox*, IM_Folder*, IM_Msg*, int offset, int size, char** text, IM_Error*);

Fetch all, or part of, the textual contents of a message.

The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument. The offset and size arguments determine which portion of the message to fetch. Callers can determine the size of a message before they retrieve it by examining the msgSizes array from the containing folder.

On success, *text will point to an array containing the requested section of the message. If the bodyBuffer field of the IM_Mbox argument is not NULL, it is assumed to point to a char array of at least size + 1 bytes, and IM_ReadMsgBody will store the requested text in this array as a null-terminated string and set *text to bodyBuffer. Otherwise, *text will point to a newly malloc’ed buffer containing the requested text as a null-terminated string.

��-��

int IM_UpdateMsgFlags(IM_Mbox*, IM_Folder*, IM_Msg*, const char* flags IM_Error*);

Updates the message flags of a message.

The caller must set the host and name fields of the IM_Mbox argument, the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument.

The flags argument is a pointer to a string of characters that specify which flags to change. The maximum length of this string is 6 characters; each position in the string represents the following flags:

Position 0 RECENT

Position 1 SEEN

InterMail C API


Each character represents a flag; T sets the flag, F clears it, and - leaves it alone. For example, a flags string of -TF causes the seen flag (position 1) to be set, and the answered flag (position 2) to be cleared. The recent flag (position 0) will be left alone, as will all other flags.

Reply Interface: im_reply.h

typedef enum IM_ReplyMsgType

{

IM_REPLY_DEFAULT_MSG_TYPE = 1, /* old name */

IM_REPLYMSG_UNKNOWN = 0, IM_REPLYMSG_AUTOREPLY = 1, IM_REPLYMSG_SIGNATURE = 2, IM_REPLYMSG_ADDRESSBOOK = 3, IM_REPLYMSG_GREENLIST = 4, IM_REPLYMSG_USERFILTER = 5,

IM_REPLYMSG_MAXTYPE} IM_ReplyMsgType;

typedef struct IM_Reply{ IM_Header _header; IM_ReplyType mode; /* Types defined in im_account.h */ char* host; /* the host name for the information */ char* text; /* text contents */ int type; /* type of contents */} IM_Reply;

The fields of this structure and their syntax are:

Position 2 ANSWERED

Position 3 FLAGGED

Position 4 DRAFT

Position 5 DELETED

_header Internal use

mode If type is 1, the auto-reply mode to use for the account, see im_account.h. If type is not 1, mode should be set to IM_REPLY_UNKNOWN.



int IM_InitReply(IM_Reply*);int IM_FreeReply(IM_Reply*);

int IM_CreateReply(IM_Account*, IM_Reply*, IM_Error*);int IM_ReadReply (IM_Account*, IM_Reply*, IM_Error*);int IM_UpdateReply(IM_Account*, IM_Reply*, IM_Error*);int IM_DeleteReply(IM_Account*, IM_Error*);

��'��&��

int IM_CreateReply(IM_Account*, IM_Reply*, IM_Error*);

If type is 1, this function defines the auto-reply text and initializes the auto-reply state for an account. The account argument must contain the smtpAddress that uniquely identifies the account. The reply argument must contain all the fields filled in. Note that the host field need not match the mssHost of the account, although this is a common arrangement.

If type is not 1, this function creates or updates the value of the account property specified by the type field.

��&��&��

int IM_ReadReply(IM_Account*, IM_Reply*, IM_Error*);

If type is 1, this function fetches the mode and text of the auto-reply message from the MSS corresponding to the account argument. The account argument must have the smtpAddress filled in.

If type is not 1, this function fetches the text of the account property associated with type.

host Logical hostname of the MSS where text and auto-reply state will be stored.

text If type is 1, the string to use for auto-reply message. Otherwise, the text of the account’s property identified by type.

type type is initialized to 1 and need not be changed for normal auto-reply operations. Other values for type can be used to define arbitrary textual properties on an account. Some non-negative values for type are used by other parts of InterMail. User applications should use negative values for type to avoid any conflicts.

InterMail C API


��-��&��

int IM_UpdateReply(IM_Account*, IM_Reply*, IM_Error*);

If type is 1, this function updates an account’s auto-reply mode, text, and host. The account argument must have the smtpAddress filled in. If the host or text field of the reply argument is NULL, these are not updated. If the mode field is IM_REPLY_NO_CHANGE, the mode is not updated.

If type is not 1, this function updates the text of the account property associated with type.

��)��&��

int IM_DeleteReply(IM_Account*, IM_Error*);

If type is 1, this function clears the auto-reply state for an account. The account argument must have the smtpAddress filled in.

If type is not 1, this function clears the text of the account property associated with type.

Class of ServiceInterface: im_cos.h

typedef struct IM_ServiceAttr {char* name;char* value;} IM_ServiceAttr;

Note: All COS attribute names are converted to lower-case in the Integrated Services Directory, so it is prudent to avoid using upper-case characters in the name field. Any of the following variations may be used to set the POP server access for an account, pref_POP, pref_Pop, or pref_pop, but when the COS information is retrieved from the Directory, it will revert to the lower-case only version, i.e., pref_pop.

typedef struct IM_ServiceDef /*Located in im_defs.h */{int num;IM_ServiceAttr* attrs;} IM_ServiceDef;

typedef struct IM_Cos{ IM_Header _header; char* name; IM_ServiceDef serviceDef;



} IM_Cos;

typedef struct IM_CosAttrDef{ IM_Header _header; int id; char* name; IM_AttributeRule rule; IM_AttributeSyntax syntax;} IM_CosAttrDef;

The value for the id field is assigned by the database.

The name field value is the Attribute name.

Note: The same considerations from IM_ServiceAttr about upper-case characters in COS attribute names apply to the name field in IM_CosAttrDef

The rule field can take one of the following values:

The syntax field can take one of the following values:

Valid values for a Boolean attribute are “1” (for true) and “0” (for false).

typedef struct IM_CosAttrDefArray{ IM_Header _header; int num; IM_CosAttrDef* attrDefs;} IM_CosAttrDefArray;

int IM_InitCos(IM_Cos*);int IM_FreeCos(IM_Cos*);int IM_InitCosAttrDef(IM_CosAttrDef*);int IM_FreeCosAttrDef(IM_CosAttrDef*);int IM_InitCosAttrDefArray(IM_CosAttrDefArray*);

IM_ATTR_RULE_COS_OVERRIDES Cos Overrides

IM_ATTR_RULE_ACCOUNT_OVERRIDES Account Overrides

IM_ATTR_RULE_LESSER Choose Lesser

IM_ATTR_RULE_GREATER Choose Greater

IM_ATTR_SYNTAX_STRING Null-Terminated String

IM_ATTR_SYNTAX_NUMERIC Integer

IM_ATTR_SYNTAX_BOOLEAN Boolean (True/False)

InterMail C API


int IM_FreeCosAttrDefArray(IM_CosAttrDefArray*);

int IM_CreateCos(IM_Cos*, IM_Error*);int IM_DeleteCos(IM_Cos*, IM_Error*);int IM_ReadCosNames(IM_StringArray*, IM_Error*);int IM_ReadCos(IM_Cos*, IM_Error*);

int IM_SetCosAttribute(IM_Cos*, char* attrName, char* attrValue, IM_Error*);int IM_UnsetCosAttribute(IM_Cos*, char* attrName, IM_Error*);

int IM_CreateCosAttribute(IM_CosAttrDef*, IM_Error*);int IM_UpdateCosAttribute(IM_CosAttrDef*, IM_Error*);int IM_DeleteCosAttribute(IM_CosAttrDef*, IM_Error*);int IM_ReadCosAttributes(IM_CosAttrDefArray*, IM_Error*);

��'��'��

int IM_CreateCos(IM_Cos*, IM_Error*);

This function creates a new COS name in the database. Only cosName field of the IM_Cos structure needs to be set. It returns error if the COS name already exists in the database.

��)��'��

int IM_DeleteCos(IM_Cos*, IM_Error*);

This function deletes a COS name and all its associated attributes from the database. Only cosName field of the IM_Cos structure needs to be set. It returns error if the COS name does not exist.

��&��'��

int IM_ReadCosNames(IM_StringArray*, IM_Error*);

This function reads all COS names from the database. The results are returned in the IM_StringArray pointer.

��&��'��

int IM_ReadCos(IM_Cos*, IM_Error*);

This function reads all the attributes associated with a COS name from the database. Only cosName field of the IM_Cos structure needs to be set. It returns error if the COS name does not exist.



��'��,��

int IM_SetCosAttribute(IM_Cos*, char* attrName, char* attrValue, IM_Error*);

This function assigns a value to an attribute for a COS. Only name field in the IM_Cos structure needs to be specified. It overwrites the attribute value if the attribute already has an assigned value.

It returns an error in the following conditions:

• COS name does not exist.

• Unknown attribute name

• No attribute value passed

��-��'��,��

int IM_UnsetCosAttribute(IM_Cos*, char* attrName, IM_Error*);

This function deletes an attribute from a COS. Only the name field in the IM_Cos structure needs to be specified.

It returns an error in the following conditions:

• COS name does not exist.

• Unknown attribute name

• Attribute does not have an assigned value

��'��'��,��

int IM_CreateCosAttribute(IM_CosAttrDef*, IM_Error*);

This function creates a new COS attribute definition in the database. id field of IM_CosAttrDef structure is ignored. The name, syntax and rule fields of IM_CosAttrDef structure must be specified. It returns an error if the attribute name already exists, or if the name does not begin with pref_ or perm_.

��-��'��,��

int IM_UpdateCosAttribute(IM_CosAttrDef*, IM_Error*);

This function modifies the rule associated with an attribute. The id field in the IM_CosAttrDef structure is ignored. The name and rule fields must be specified. It returns an error if the attribute does not exist.

InterMail C API


��)��'��,��

int IM_DeleteCosAttribute(IM_CosAttrDef*, IM_Error*);

This function deletes a COS attribute definition from the database if it is not used in a COS definition otherwise it returns an error. Only the name field of IM_CosAttrDef structure needs to be specified. It returns an error if the attribute does not exist.

��&��'��,��

int IM_ReadCosAttributes(IM_CosAttrDefArray*, IM_Error*);

This function reads all COS attribute definitions from the database. The data is returned in the IM_CosAttrDefArray argument.

Configuration InformationInterface: im_config.h

typedef struct IM_Config{ IM_Header _header; char* name; char* host; char* prog; char* defvalue; char* value;} IM_Config;



name Name of the configuration variable, e.g., netTimeout.

host Logical hostname. For example, if name is netTimeout and host is mtahost, then this IM_Config refers to the configuration variable /mtahost/common/netTimeout, or /*/common/netTimeout if that is not present. If host is NULL, then the local host is assumed.

prog Name of the InterMail program requested, e.g., mta. This does not have to be the name of an actual program, as long as there is a config key associated with this program in the Configuration database. For example, if prog equals progname and name is netTimeout, then /*/progname/netTimeout will be retrieved, or /*/common/netTimeout if that is not present.



int IM_InitConfig(IM_Config*);int IM_FreeConfig(IM_Config*);int IM_ReadConfig(IM_Config*, IM_Error*);

��'��

int IM_InitConfig(IM_Config*)

This function initializes an IM_Config structure.

��'��

int IM_FreeConfig(IM_Config*)

This function frees the IM_InitConfig structure.

��&��'��

int IM_ReadConfig(IM_Config*, IM_Error*)

IM_ReadConfig uses the information in IM_Config to access information in the InterMail Configuration database. It fills in the value field with information from the Configuration database. The name, field (and optionally the host and prog fields) must be specified to identify the desired configuration value. It fills the value field with the defvalue argument if it fails to find the information in the Configuration database.

MIME InformationInterface: im_msg.h

typedef struct IM_MimeInfo{ IM_Header _header; void* _internalID; IM_Msg* _msg; int isMultiPart; int isMessagePart; int childCount; int headerOffset; int bodyOffset; int headerLength; int totalSize; int numLines;

defvalue The default value, the value to return if the configuration variable is not found and if there is no wildcard key (like /*/common/...) which applies. This can be NULL if no default is desired.

value Returned configuration parameter.

InterMail C API


char* contentTransferEncoding; char* mainContentType; char* subContentType; char* contentId; char* contentDescription; char* boundary; char* contentMD5; IM_StringArray contentDisposition; IM_StringArray contentLanguage; IM_StringArray parameters;} IM_MimeInfo;

IM_MimeInfo describes a message or a particular body part of that message. A message consists of a “top-level” body part that describes the entire message; this body part may have subparts, which may in turn have other subparts.




_msg Internal use.

isMultiPart Set to TRUE (1) if this is a multipart body part, otherwise FALSE (0).

isMessagePart Set to TRUE if this is a message/rfc822 body part

childCount The number of child body parts this body part has, if isMultiPart is TRUE.

headerOffset The offset in bytes of the body part header from the start of the message. For the top-level body part, this means the offset to the start of the message header; it's always 0. For other body parts, this means the offset to the start of the MIME header.

bodyOffset The offset of the body part data from the start of the message. For the top-level body part; this means the offset to the start of the body; for other body parts, it means the offset to the line right after the MIME header (that is, right after the blank line).

headerLength The length of the header in bytes.

totalSize The total size of this body part in bytes, including the header.



numLines The number of lines in the body part data. If the body part is encoded, this refers to the number of lines in the text after encoding.

contentTransferEncoding The value of the Content-Transfer-Encoding header for this bodypart, or an empty string if there isn’t one.

mainContentType The first half of the media type from the Content-Type: header for this bodypart.

subContentType The media subtype from the Content-Type: header. For example, a text/plain bodypart will have a mainContentType of “text” and a subContentType of “plain”.

contentId The value of the Content-Id header, or an empty string if there isn't one.

contentDescription The value of the Content-Description header, or an empty string if there isn't one.

boundary The value of the boundary parameter in the Content-Type header, or an empty string if there isn't one.

contentMD5 The value of the Content-MD5 header, or an empty string if there isn't one.

contentDisposition A string array describing the Content-Disposition header. If the Content-Disposition header is not present, this array is empty. Otherwise it contains a disposition type string followed by a series of attribute/value pairs. See RFC 1806 for details. Example: Content-Disposition: attachment; filename=x is returned as the three-element array (attachment, filename, x).

contentLanguage A string array describing the Content-Language header. If the Content-Language header is not present, this array is empty. Otherwise it contains a list of language tags. See RFC1766 for details.

InterMail C API


The functions below manipulate the IM_MimeInfo structure.

int IM_InitMimeInfo(IM_MimeInfo*);int IM_FreeMimeInfo(IM_MimeInfo*);

The function below retrieves MIME information in a given message:

int IM_ReadMsgMimeInfo(IM_Mbox*, IM_Folder*, IM_Msg*, IM_MimeInfo* parent, int index, IM_MimeInfo* output, IM_Error*);

��

int IM_InitMimeInfo(IM_MimeInfo*);

This function initializes the IM_MimeInfo structure.

��

int IM_FreeMimeInfo(IM_MimeInfo*);

This function frees the IM_MimeInfo structure.

��&��


The caller must set the host and name fields of the IM_Mbox argument, and the pathname field of the IM_Folder argument, and the msgRef field of the IM_Msg argument. These arguments specify which message to fetch information about and where to find it.

If the parent argument is NULL, then the index argument is ignored and information about the message’s top-level body part (i.e. the message as a whole) is returned.

If the parent argument is non-NULL and it points to an IM_MimeInfo describing a multi-part body part, then the index argument must specify the index of a child body part. This index must be between 0 and parent->childCount - 1. Information about that child body part will be returned.

parameters A string array describing the Content-Type parameters. It contains a series of attribute/value pairs. For example, a Content-Type: text/plain; name=value, name2=value header would cause the parameters array to contain the four-element list (name, value, name2, value2).



If the parent argument is non-NULL and it points to an IM_MimeInfo structure describing a message/rfc822 body part, then the index argument is ignored, and information about the body part contained by the message will be returned.

On success, the structure pointed to by the output argument will contain the requested information about the message.

Here is a sample piece of code that fetches information about the complete body part tree for a message.

voiddumpSubMimeInfo(IM_Mbox* mbox, IM_Folder* folder, IM_Msg* msg, IM_MimeInfo* minfo, int level, IM_Error* err){ char pad[100];

if (level >= 100) return;

memset(pad, ’ ’, level); pad[level] = ’\0’; printf("%sIM_MimeInfo:\n" " %s%s childCount=%d hoff=%d boff=%d hlen=%d" " totsize=%d lines=%d\n" " %scte=\"%s\" ct=\"%s/%s\" cid=\"%s\" cdesc=\"%s\"\n" " %sbound=\"%s\" cmd5=\"%s\"\n", pad, pad, minfo->isMultiPart ? "multi" : minfo->isMessagePart ? "msg" : "single", minfo->childCount, minfo->headerOffset, minfo->bodyOffset, minfo->headerLength, minfo->totalSize, minfo->numLines, pad, minfo->contentTransferEncoding, minfo->mainContentType, minfo->subContentType, minfo->contentId, minfo->contentDescription, pad, minfo->boundary, minfo->contentMD5);

if (minfo->isMessagePart || minfo->isMultiPart) { int i; int count; IM_MimeInfo child_minfo;

IM_InitMimeInfo(&child_minfo); count = (minfo->isMultiPart ? minfo->childCount : 1); for (i = 0; i < count; i++) { IM_ReadMsgMimeInfo(mbox, folder, msg, minfo, i, &child_minfo, err); dumpSubMimeInfo(mbox, folder, msg, &child_minfo, level+1, err); } IM_FreeMimeInfo(&child_minfo);

InterMail C API


}}

voiddumpMimeInfo(IM_Mbox *mbox, IM_Folder *folder, IM_Msg *msg, IM_Error*err){ IM_MimeInfo minfo; IM_InitMimeInfo(&minfo); if (IM_ReadMsgMimeInfo(mbox, folder, msg, NULL, 0, &minfo, err) == IM_FAILURE) fprintf(stderr, "ReadMsgMimeInfo failed!\n"); else dumpSubMimeInfo(mbox, folder, msg, &minfo, 0, err); IM_FreeMimeInfo(&minfo);}

Log MessagesThis class can create new InterMail log files, append entries to a log file and fetch the text that would be generated for an entry. It works together with the IM_LogContext class.

Interface: im_log.h

typedef enum IM_Severity{ IM_SEVERITY_UNKNOWN = 0, IM_SEVERITY_NOTIFICATION = 1, IM_SEVERITY_WARNING = 2, IM_SEVERITY_ERROR = 3, IM_SEVERITY_URGENT = 4, IM_SEVERITY_FATAL = 5 IM_SEVERITY_MAX = IM_SEVERITY_FATAL} IM_Severity;

typedef struct IM_LogMsg{ IM_Header _header; IM_Severity severity; int msgId; char* type; IM_StringArray args; char* text; char* logName; } IM_LogMsg;



The information about log messages is conveyed via the structure IM_LogMsg:

These functions manipulate the IM_LogMsg structure:

int IM_InitLogMsg(IM_LogMsg*, IM_Error*);int IM_FreeLogMsg(IM_LogMsg*);int IM_CreateLogFile(IM_LogMsg*, IM_Error*);int IM_WriteLogMsg(IM_LogMsg*, IM_Error*); int IM_ReadLogMsgText(IM_LogMsg*, IM_Error*);

Example

IM_LogMsg lg; IM_Error er; IM_InitError(&er); IM_InitLogMsg(&lg); lg.logName = strdup(“myprog”); lg.messageType = strdup(“ProcSomethingBad”); lg.args.num = 3; char *args[3]; args[0] = “arg1”; args[1] = “arg2”; args[2] = “arg3”; lg.args.strings = args; lg.severity = IM_SEVERITY_URGENT; IM_WriteLogMsg(&lg, &er); IM_GetLogMsgText(&lg, &er); printf(“log message looks like: %s\n”, lg.text); lg.args.strings = 0; IM_FreeLogMsg(&lg);

_header Internal use

severity The severity of the condition that is prompting the log message.

type A short string, corresponding to an InterMail message number, which describes the type of message to log; for example, PopConnMade.

msgId An InterMail message number identifying the message. For example, the message id for PopConnMade is 4325385. In almost all cases the caller should specify type rather than msgId to identify a message.

args A list of arguments to include in the log entry. Most message numbers expect a pre-determined list of arguments, e.g., PopConnTimedOut expects the first args value to be the number of seconds that passed before the client timed out.

logName Name of the log file. This is only used when the first log entry is written, or when the log file is created.

InterMail C API


��

int IM_InitLogMsg(IM_LogMsg* logmsg, IM_Error* error);

Initializes the IM_LogMsg structure. IM_InitLogMsg() must be called before attempting to use any function which uses IM_LogMsg.

��

int IM_FreeLog Msg(IM_LogMsg* logmsg);

Free the IM_LogMsg structure.

��'��

int IM_CreateLogFile(IM_LogMsg* logmsg, IM_Error *error);

Creates or opens the log file, if it has not been created or opened already, using logName as the base part of the filename. For example if logName is mta, then this function will attempt to open the file mta.server-hostname.current-date-and-time.log, creating it if necessary. All further log messages will go to that log file. If a log file has already been opened this function does nothing.

��+��

int IM_WriteLogMsg(IM_LogMsg* logmsg, IM_Error* error);

Writes a log message to the log file. If the log file hasn’t been opened, then logName specifies the base part of the filename.

��&��$�!�

int IM_ReadLogMsgText(IM_LogMsg* logmsg, IM_Error* error);

Formats a log message and returns it in the text field of the logmsg.

Log ContextThis structure is used to describe context information, which is used when generating log messages. Any log message that is generated will have context information appended to it. It is not necessary to set the log context, but it can be convenient to ensure that log messages always contain consistent information. The format of the context strings is not very important; they will be written to the log file as-is.

Interface: im_log.h

typedef struct IM_LogContext{ IM_Header _header; char* mailUser; char* mailHost;



char* mailbox; char* from; char* folder; char* msgId; char* origMsgId; char* cmd; int port; int size; char* destHost; char* fromHost;} IM_LogContext;

The information about log context is conveyed via the structure IM_LogContext:

_header For internal use.

mailUser The current username or recipient address. If this is set, then it will appear as user=xxx in the log file.

mailHost The current mail server we are talking to or trying to connect to. If this is set, then it will appear as mss=xxx in the log file.

mailbox The current mailbox id. If this is set, then it will appear as mbox=xxx.

from The current from address. If this is set, then it will appear as from=xxx.

folder The current folder name. If this is set, then it will appear as fldr=xxx.

msgId The message ID of the current message. If this is set, then it will appear as msgid=xxx.

origMsgId The original message ID of the current message. If this is set, then it will appear as origMsgid=xxx.

cmd The current client command. If this is set, then it will appear as cmd=xxx.

port Current port number. If this is set, then it will appear as port=xxx.

size The size in bytes of the current message. If this is set, then it will appear as size=xxx.

fromHost The current client host. If this is set, then it will appear as fromhost=xxx.

destHost The current destination host. If this is set, then it will appear as desthost=xxx.

InterMail C API


These functions manipulate the IM_LogContext structure:

int IM_InitLogContext(IM_LogContext*, IM_Error*);int IM_FreeLogContext(IM_LogContext*);int IM_UpdateLogContext(IM_LogContext*, IM_Error*);int IM_ReadLogContext(IM_LogContext*, IM_Error*);

For instance, if a PopConnMade log message is written to the log with no arguments, but with the mailUser context variable set to tmpusr7001, mailHost set to paris, port set to 5681, and mailbox set to 7001, then the following text will be generated in the log file (as a single line):

19980518 125545971-0700 paris popserv 23904 10 12 Note;PopConnMade (66/9)user=tmpusr7001:mss=paris:port=5681:mbox=7001

��'��!�

int IM_InitLogContext(IM_LogContext* logc, IM_Error* error);

Initializes the IM_LogContext structure. IM_InitLogContext() must be called before attempting to use any function which uses IM_LogContext.

��'��!�

int IM_FreeLogContext(IM_LogContext* logc);

Free the IM_LogContext structure.

��-��'��!�

int IM_UpdateLogContext(IM_LogContext* logctx, IM_Error* error);

Update the log context to match the information in logctx. Fields become disabled if they are updated to a NULL value. Subsequent log messages will include the updated log context information.

��&��'��!�

int IM_ReadLogContext(IM_LogContext* logctx, IM_Error* error);

Read the current log context and save the context information in logctx.



Compiling, Linking, and RunningInterMail header files are installed in the include directory at the top of the InterMail product directory. InterMail libraries are installed in the lib directory at the top of the InterMail product hierarchy. Additional required libraries come from your local operating system.

Some of the libraries that are accessed by libim.so will spawn threads to do some of their work, so all applications that use the API are inherently multi-threaded. Most platforms have special requirements for compiling and linking multi-threaded applications, and examples are given below for particular operating systems.

Currently, some portions of the InterMail C-API are not re-entrant, so unpredictable errors may occur if functions in this library are called simultaneously by more than one thread in the same process. If the InterMail C-API is used by multiple threads in a single process, you should implement a single mutex that is always locked before any of the API functions are invoked.

Users of the API should always have a suitable value for the environment variable $INTERMAIL A great deal of information about the InterMail software is determined by a configuration database stored under the $INTERMAIL directory, so it is imperative that applications use the correct location.

While it may be possible to use a “C” compiler, the C++ compiler is recommended, and the C++ linker is required because libomu, which you must link with, is a C++ library.

The header files are compatible with both C and C++ source files.

Note that your Makefile or compile command line should specify where to find these files. They are located below the directory specified by the $INTERMAIL variable, in the include subdirectory. A Makefile is strongly recommended, given the number files to include and link.

Sun Microsystems Solaris 2.5.1 and 2.6To compile files for multi-threaded applications on Solaris with the SPARCWorks C or C++ compiler, use the -mt flag.

cc -mt -I$INTERMAIL/include -c myfile.c

To link an application with the InterMail API on Solaris, use the following command as an example.

CC -mt -o application object-files… \-L$INTERMAIL/lib -lim –lomu \

InterMail C API


Digital UNIXTo compile files for multi-threaded applications on Digital UNIX, use the -pthread flag.

cxx -pthread -I$INTERMAIL/include -c myfile.c

To link an application with the InterMail API on Digital UNIX, use the following command as an example.

cxx -pthread -o application object-files… \-L$INTERMAIL/lib -lim -lomu \

Silicon Graphics IRIX 6To compile files for multi-threaded InterMail applications on Silicon Graphics IRIX, use the –32 and –signed flags and the following pre-processor definitions.

cc –32 –signed -D_SGI_REENTRANT_FUNCTIONS -D_SGI_MP_SOURCE \ -I$INTERMAIL/include -c myfile.c

To link an application with the InterMail API on Silicon Graphics IRIX, use the following command as an example. Note that the C++ linker is used, even though your source code may be written in C.

CC -o application object-files… \-L$INTERMAIL/lib -lim -lomu \

File SummaryThe following is a list of the InterMail C-API header files:

im_account.him_config.him_cos.him_defs.him_domain.him_error.him_folder.him_log.him_mbox.him_msg.him_reply.him_stringarray.him_types.h

InterMail API libraries:

libim.so (link to libim.4. x)libomu.so (link to libomu.4.x)



Function SummaryThe following is a listing of the InterMail C-API functions.

Library

int IM_InitLibrary();

int IM_InitApplication(const char* appName, IM_Error*);

int IM_SetMSSConnPoolSize(int poolSize, IM_Error*);

IM_Error

int IM_InitError(IM_Error*);

int IM_FreeError(IM_Error*);

int IM_SetError(IM_Error*, int errNum, const char* string);

int IM_GetErrorMnemonic(const IM_Error*, char* buf, int bufsize);

int IM_Errno2Mnemonic(int errNum, char* buf, int bufsize);

IM_StringArray

int IM_InitStringArray(IM_StringArray*);

int IM_FreeStringArray(IM_StringArray*);

int IM_CopyStringArray(IM_StringArray* dst, const IM_StringArray* src);

int IM_ZeroStringArray(IM_StringArray*);

IM_Domain

int IM_InitDomain(IM_Domain*);

int IM_FreeDomain(IM_Domain*);

int IM_CopyDomain(IM_Domain* dst, const IM_Domain* src);

int IM_ReadDomain(IM_Domain*, IM_Error*);

int IM_ReadDomains(char* from, char* till, int max, IM_StringArray* domains, IM_Error*);

int IM_ReadSubDomains(char* topDomain, char* from, char* till, int max, IM_StringArray* domains, IM_Error*);

int IM_CreateDomain(IM_Domain*, IM_Error*);

int IM_UpdateDomain(IM_Domain*, IM_Error*);

int IM_DeleteDomain(IM_Domain*, IM_Error*);

InterMail C API


IM_Account

int IM_InitAccount(IM_Account*);

int IM_FreeAccount(IM_Account*);

int IM_ReadAccount(IM_Account*, IM_Error*);

int IM_ReadAccounts(char* topDomain, char* from, char* till, int max, IM_StringArray*, IM_Error*);

int IM_ReadPOP3(const char* pop3, IM_Account*, IM_Error*);

int IM_CreateAccount(IM_Account*, IM_Error*);

int IM_UpdateAccount(IM_Account*, IM_Error*);

int IM_UpdateAccountAddr(IM_Account*, IM_Account* newAddress, IM_Error*);

int IM_DeleteAccount(IM_Account*, IM_Error*);

int IM_ReadAlias(const char* alias, IM_Account*, IM_Error*);

int IM_ReadAccountAliases(IM_Account*, IM_StringArray*, IM_Error*);

int IM_CreateAlias(IM_Account*, const char* alias, IM_Error*);

int IM_DeleteAlias(const char* alias, IM_Error*);

int IM_ReadAccountForwards(IM_Account*, IM_StringArray*, IM_Error*);

int IM_CreateForward(IM_Account*, const char* forwardTo, IM_Error*);

int IM_DeleteForward(IM_Account*, const char* forwardTo, IM_Error*);

int IM_EnableAccountForwards(IM_Account*, IM_Error*);

int IM_DisableAccountForwards(IM_Account*, IM_Error*);

int IM_ResetAcCos(IM_Account*, IM_Error*);

int IM_UpdateAcCos(IM_Account*, char* name, char* value, IM_Error*);

int IM_DeleteAcCos(IM_Account*, char* name, IM_Error*);

int IM_HashPassword(char* password, char* hashPassword, int len, IM_PwHashType);



int IM_CheckPassword(char* password, char* hashPassword, IM_PwHashType);

IM_Mbox

int IM_InitMbox(IM_Mbox*);

int IM_FreeMbox(IM_Mbox*);

int IM_ReadMbox(IM_Mbox*, IM_Error*);

int IM_CreateMbox(IM_Account*, const char* welcomeMsgId, IM_Mbox*, IM_Error*);

int IM_DeleteMbox(IM_Mbox*, IM_Error*);

IM_Folder

int IM_InitFolder(IM_Folder*);

int IM_FreeFolder(IM_Folder*);

int IM_ReadFolder(IM_Mbox*, IM_Folder*, IM_Error*);

int IM_CreateFolder(IM_Mbox*, IM_Folder*, IM_Error*);

int IM_RenameFolder(IM_Mbox*, IM_Folder*, const char* dstname, IM_Error*);

int IM_DeleteFolder(IM_Mbox*, IM_Folder*, IM_Error*);

int IM_ScanFolderMsgs(IM_Mbox*, IM_Folder*, int numMsgs, IM_Msg**, IM_Error*);

int IM_DeleteFolderMsgs(IM_Mbox*, IM_Folder*, int numMsgRefs, int* msgRefs, IM_Error*);

int IM_MoveMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int numMsgRefs, int* msgRefs, IM_Error*);

int IM_CopyMsgs(IM_Mbox*, IM_Folder* src, IM_Folder* dst, int numMsgRefs, int* msgRefs, IM_Error*);

IM_Msg

int IM_InitMsg(IM_Msg*);

int IM_FreeMsg(IM_Msg*);

int IM_ReadMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);

int IM_ReadMsgHeader(IM_Mbox*, IM_Folder*, IM_Msg*, const char* hdrLabel, char** hdrValue, IM_Error*);

int IM_ReadMsgBody(IM_Mbox*, IM_Folder*, IM_Msg*, int offset, int size, char** text, IM_Error*);

InterMail C API


int IM_CreateMsg(IM_Mbox*, IM_Folder*, const char* from, const char* rfc822message, IM_Msg*, IM_Error*);

int IM_UpdateMsgFlags(IM_Mbox*, IM_Folder*, IM_Msg*, const char* flags, IM_Error*);

int IM_DeleteMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);

IM_MimeInfo

int IM_InitMimeInfo(IM_MimeInfo*);

int IM_FreeMimeInfo(IM_MimeInfo*);


IM_Reply

int IM_InitReply(IM_Reply*);

int IM_FreeReply(IM_Reply*);

int IM_ReadReply(IM_Account*, IM_Reply*, IM_Error*);

int IM_CreateReply(IM_Account*, IM_Reply*, IM_Error*);

int IM_UpdateReply(IM_Account*, IM_Reply*, IM_Error*);

int IM_DeleteReply(IM_Account*, IM_Error*);

IM_Cos

int IM_InitCos(IM_Cos*);

int IM_FreeCos(IM_Cos*);

int IM_ReadCos(IM_Cos*, IM_Error*);

int IM_ReadCosNames(IM_StringArray*, IM_Error*);

int IM_CreateCos(IM_Cos*, IM_Error*);

int IM_SetCosAttribute(IM_Cos*, char* name, char* value, IM_Error*);

int IM_UnsetCosAttribute(IM_Cos*, char* name, IM_Error*);

int IM_DeleteCos(IM_Cos*, IM_Error*);

IM_CosAttrDef

int IM_InitCosAttrDef(IM_CosAttrDef*);

int IM_FreeCosAttrDef(IM_CosAttrDef*);

int IM_CreateCosAttribute(IM_CosAttrDef*, IM_Error*);

int IM_UpdateCosAttribute(IM_CosAttrDef*, IM_Error*);

int IM_DeleteCosAttribute(IM_CosAttrDef*, IM_Error*);



IM_CosAttrDefArray

int IM_InitCosAttrDefArray(IM_CosAttrDefArray*);

int IM_FreeCosAttrDefArray(IM_CosAttrDefArray*);

int IM_ReadCosAttributes(IM_CosAttrDefArray*, IM_Error*);

IM_Config

int IM_InitConfig(IM_Config*);

int IM_FreeConfig(IM_Config*);

int IM_ReadConfig(IM_Config*, IM_Error*);

IM_LogContext

int IM_InitLogContext(IM_LogContext*);

int IM_FreeLogContext(IM_LogContext*);

int IM_ReadLogContext(IM_LogContext*, IM_Error*);

int IM_UpdateLogContext(IM_LogContext*, IM_Error*);

IM_LogMsg

int IM_InitLogMsg(IM_LogMsg*);

int IM_FreeLogMsg(IM_LogMsg*);

int IM_ReadLogMsgText(IM_LogMsg*, IM_Error*);

int IM_WriteLogMsg(IM_LogMsg*, IM_Error*);

int IM_CreateLogFile(IM_LogMsg*, IM_Error*);


6InterMail Perl API

This chapter describes the InterMail Perl API (SwCom::Error, SwCom::WebSession, and SwCom::Mail), which operates on the following objects:

• Error

• WebSession

• Class-of-Service attributes

• Classes of Service

• Domains

• Accounts

• Auto-reply messages

• Mailboxes

• Folders

• Messages

IntroductionThe programming interface relies on the object-oriented features of Perl 5, and uses a Perl binary distribution provided by Software.com.

The Perl classes making up SwCom::Error, SwCom::WebSession, and SwCom::Mail are built upon the corresponding objects in the InterMail C API and depend strongly on the conventions used in it. Users are encouraged to read Chapter 6 for an understanding of the fundamental concepts of InterMail administrative objects and the requirements for parameters of various function calls.

InterMail Perl API classes closely mimic the InterMail C API. Because of the differences between C and Perl, some Perl API functions deviate from their C counterparts, but they usually follow an intuitive mapping when the object-oriented Perl supports a simpler form of expression than the C syntax would allow.



General Usage NotesDue to various operating systems’ restrictions, Perl scripts that use the SwCom::Error, SwCom::WebSession, and SwCom::Mail classes (hereby referred to as the InterMail Perl API classes) can only be executed by a specially built, InterMail Perl interpreter. The fundamental Perl source code was not changed for this version of the interpreter, but the compilation and linking options for programs that spawn threads differ from the configuration in the standard Perl distribution.

Hooking Classes in Your ScriptsTo use the InterMail Perl API classes, place the following statements in the Perl script. For example, before using any SwCom::Mail classes, functions, or constants:

use SwCom::Mail::All;im_init();

This will import the necessary definitions, including the definitions of the symbolic constants which enumerate the types of domains, accounts, password encodings, etc., and then initialize the InterMail library.

Note: In order to allow InterMail services to use this script, the user must first initialize the library by calling the im_init() function.

Most InterMail objects contain fields that are implemented as enumerations, or symbolic constants. Consult the C API documentation for the names of relevant constants and use them in accordance with their “C API purpose”.

For example, this statement in Perl:

print ′IM_DOMAIN_NON_AUTH = ′, IM_DOMAIN_NON_AUTH, ″\n″;

will produce the following output:

IM_DOMAIN_NON_AUTH = 78

in accordance with the C API definition in IM_domain.h:

typedef enum IM_DomainType...

IM_DOMAIN_NON_AUTH = ′N′,...

} IM_DomainType;

The symbolic constants in the InterMail API are implemented as dynamically defined subroutines in Perl. This may cause some confusion if these constants are combined in arithmetic expressions. Currently, you never need to combine these constants to use the Perl API, but should you need to mix these constants in an expression, prefix them with “&” or append “()” to them. Using either of these conventions informs the Perl interpreter that these symbols should be treated as subroutines, which triggers the necessary “AUTOLOAD” functionality to define them.

InterMail Perl API


Underlying Libraries and VersioningA prerequisite to execute a Perl script using any of the Perl API classes is to have all underlying libraries on your system at locations where they can be found by the run-time linker. This includes:

• System libraries, such as libc.so, libC.so, libpthread.so, etc. Theoretically, these libraries should always be in the right directories, e.g. in /usr/lib or /usr/shlib (depending on the platform).

• InterMail shared libraries: currently there are two of them, libomu.so and libim.so. For each of these libraries, the containing directory (usually $INTERMAIL/lib) should be part of the environment variable $LD_LIBRARY_PATH.

• Perl modules making up the InterMail Perl API class library; these should be at a location where the Perl interpreter can find them. The Perl interpreter installed with InterMail (typically, $INTERMAIL/perl/bin/perl) knows how to find the standard version of these libraries in the normal location. You may use a custom version of the SwCom::Mail by setting the environment variable $PERL5LIB so that your private library’s location is searched before the one in the Perl package.

The Perl API library provides a Perl interface to the InterMail C API (libim.so), which itself works as a gateway to InterMail foundation classes (libomu.so), database libraries and so forth. A user does not need to worry about software layers underneath the C API library, which encapsulates the complexity of InterMail internals and screens users from the ongoing changes in them. From time to time, the C API will change in a way that impacts the Perl API, which may cause some older scripts to fail with the updated InterMail. The release notes will describe all known incompatibilities.

The version of InterMail for which the InterMail Perl API was built is available in Perl by calling the function im_version(). Users may want to check the InterMail version before doing anything else in a script. For example:

use SwCom::Mail::All;im_init();my $version = im_version();if ($version =~ /^4\./) { print ?Version=$version\n?;

# prints something like: “Version=4.0-1.5”} else { die ?Script assumes InterMail 4.xx; current version is $version\n?;}



Error HandlingMost of the methods return 1 for success and 0 otherwise. This is a common (but not universal) convention. In a few cases it is more convenient and natural to return a list on success, and undef for failure.

Detailed error information from the InterMail C API can be examined by calling the following Perl functions:

• im_errnum()

• im_errstr()

• im_errmnemonic()

im_errnum() returns a non-zero value if an InterMail operation failed. In this case, the im_errnum()’s return code is the InterMail’s error number, the full or mnemonic description of the reason why the operation failed, should be available as a string returned by the functions im_errstr() or im_errmnemonic(), respectively.

It is useful to use the following definition of an error handling Perl subroutine, which will be repeatedly used in examples:

{my ($n, $s);if($n = im_errnum()) {

$s = im_errstr() || im_errormnemonic() ||’(no further information)’;print "** Error $n: $s\n";

return;}print "** OK\n";

}

Classes and ObjectsThis section illustrates the general ideas and conventions of using Perl API objects, using the Domain object as an example.

It is important to understand the difference between creating a domain as a record in a directory database and creating a Perl object of the type Domain. The latter works just as a place-holder for information to be transferred to or from C functions that operate on a Directory database and may, in particular, actually create a domain as a new record in the database.

To create a Perl object of the type Domain, invoke a class constructor, through a method new:

$domain=new Domain( type => IM_DOMAIN_LOCAL, name => ’example.com’, ...);

InterMail Perl API


To create a new domain record in the directory database, call the method Create() on a Perl object previously constructed as shown above:

$domain->Create();

Note that Perl objects and the InterMail objects they refer to may be (and in practice, often will be) out of sync. One will likely create and use “incomplete” Perl objects the ones in which some fields are undefined or are not valid. The only way to obtain a “snapshot” of a real InterMail object is to invoke the method Read() from the corresponding Perl class. (Theoretically, by the time the information about field values is passed to a user script by a Read() method, the underlying InterMail object may change due to another process's activity. But this is a general problem with concurrent manipulation of database records and is not specific to SwCom::Mail.)

The same is true for objects of all other Perl API classes and their corresponding InterMail entities.

All class constructors (new() subroutines) use call-by-pairs format, where one can conveniently assign a value to all or some attributes of the object. It is not necessary to set every field of an object for all operations most methods use only a small subset of an object’s fields. In some cases (the Read() method) most of the fields are assigned a (new) value as a result of a method call.

One can also directly assign values to an object's fields, like this:

$domain->relayHost(’hostess’);

The value of an object's field can be accessed this way:

$host=$domain->relayHost();

Note that it is possible to set or get the value of an object's field by using this syntax:

$domain->{relayHost} = ’hostess’;$host = $domain->{relayHost};

This syntax is discouraged, since the misspelling of a field name will go unnoticed until long after the point where the error occurred. Setting/getting the value of a field through function calls is safe in the example above, the class Domain must have a field named “relayHost”; otherwise these functions would fail immediately.

All Perl API classes define the method Dump() for returning the information on the field values as a string, in a format that is suitable for direct printing on a stream. One can use the following construction, for example:

print STREAM object->Dump();

Note: For a field that takes an integer value from a finite set, corresponding to a C enumeration, the value of the field will be printed not as an integer but as the name of the enumeration constant.

This chapter uses the term instance method (function) for functions that can only be invoked with an object, like this:

object_reference->method(...)



Class methods (functions) do not need an object to operate upon and can be invoked this way:

class_name::method(...)

Class methods resemble static methods in C++.

SwCom::Error Class ReferenceDescription

Provides access to InterManager errors. The SwCom::Error class contains information about why an operation was unsuccessful.

Synopsis

my $err = new SwCom::Error($type, $number, $string);print $err->Type();print $err->String();die if ($err->Number() > 5);my $err2 = new_from_error SwCom::Error($err);

Methods

• new SwCom::Error(type, number, string)Constructor for the Error object. Initializes the Error object with the supplied arguments. Returns a reference to a SwCom::Error object.

• new_from_error SwCom::Error(Error)Constructor for the Error object. Returns a reference to a SwCom::Error object. Constructs a new Error object from the given Error object.

• Type()This method returns a string describing the source of the error, thus allowing for overlapping error numbers. Valid types are: ’LDAP’, ’IM’.

• String()This method returns a string describing the error.

• Number()This method returns an error id number.

SwCom::WebSession Class ReferenceDescription

Manages WWW administration sessions. The SwCom::WebSession class provides functions for managing WWW administrative sessions. After a session is created, it is identified by a unique token that gets passed from HTTP request to HTTP request. These tokens are time sensitive and can either expire, or be explicitly killed with the Delete() method.

InterMail Perl API


Synopsis

$ws = new SwCom::WebSession;die unless $ws->Create($ipaddr, $login, $passwd, $md5passwd);die unless $ws->Validate($ipaddr, $token);$token = $ws->GetToken();if ($ws->Delete()) { print "Log out successful"; }$ldap_session = $ws->GetLDAPSession();$err = $ws->GetError();$ws->SetError($err);

Methods

• new SwCom::WebSession()SwCom::WebSession constructor. Returns a reference to a new WebSession object.

• Create($ipaddr, $login, $password, $md5passwd)Method used to authenticate a new user and activate a new Web Session for the user. It sets up an SwCom::IMgr::Session object representing the active Web Session. If $password is defined, the user is authenticated by comparing the plain text password stored in their account. If the $md5passwd is defined, the user is authenticated by comparing the hashed password value read from their account. Both may be supplied.

Returns 1 if successful, 0 otherwise.

• Update()Modifies the values persisted for the active SwCom::WebSession object. The values are stored in a hash upon the object. The valid keys are token, ipaddr, login, passwd, encpasswd, smtpAddress, popAddress, mssHost, emailIntID, and services. If the key ‘token’ is undefined, a new token will be calculated and stored for the active session. The service is a hash of key/value pairs, where each key is a valid Class of Service attribute.

Returns 1 if successful.

• Validate($ipaddr, $token)This method verifies that a given token exists and has not timed out. It sets up an SwCom::IMgr::WebSession object for the active session identified by the token.

Returns a new SwCom::IMgr::WebSession object if successful, 0 otherwise.

• GetToken()Returns a unique ASCII string that identifies the WebSession. This string must be passed in every HTTP request of a web session.

• Delete()This method is used to explicitly end a running WebSession. The token identified with the Web session is invalidated. The LDAP session is closed (if necessary) by “unbinding” the user. This function is useful for implementing 'logout' buttons. Returns 1 on success, 0 otherwise.



• GetLDAPSession()This method returns a reference to a SwCom::IMgr::Session object. This reference can be used to construct objects derived from SwCom::IMgr::Entry.

• GetError()Returns a reference to a SwCom::Error object that describes the reason for most recent failed operation. Not reset on success.

• SetError($err) | SetError (type, number, string)Sets the Error object within the WebSession object. Input could either be an Error object or error type, number and string.

SwCom::Mail Class ReferenceThis section describes the attributes and methods of all classes in the InterMail Perl API.

CosAttributeThe class CosAttribute (Class of Service Attribute) has the following fields:

A new CosAttribute object can be created this way:

$cos = new CosAttribute( name => ′pref_quota′, rule => IM_ATTR_RULE_COS_OVERRIDES, syntax => IM_ATTR_SYNTAX_NUMERIC,};

InterMail is installed with a large set of pre-defined CosAttributes. Most of the time, you will be referencing the existing attribute definitions, rather than creating new ones.

id Integer

name String. All CosAttribute names must begin with a prefix of “perm_” or “pref_”.

rule enum IM_AttributeRule (see Chapter 5)

syntax enum IM_AttributeSyntax (see Chapter 5)

InterMail Perl API


Note: It is best to avoid upper-case characters when accessing or defining the name fields of CosAttribute and Cos objects. All upper-case letters in name fields will be converted to lower-case before they are stored, or queried, in the database. This means it is possible to look up CosAttributes and Cos objects using mixed case, but the return values from CosAttribute::ReadAll() will use no uppercase. For Cos::Read() and Account::Read(), the keys of the serviceDef, acCos, and resultCos hashes will likewise be all lower-case.

The class CosAttribute defines the following methods:

&��,��9:9;

Prerequisites

None. This is a class method, which must be run as follows:

my @attr_list = CosAttribute::ReadAll();

Implementation

Calls IM_ReadCosAttributes().

Return Values

Returns a list of references to CosAttribute objects on success, undef on failure.

'��9:9;

Prerequisites

The name, rule, and syntax fields must be defined. The name field must not conflict with any existing CosAttribute.

Implementation

Calls IM_CreateCosAttribute().

Return Values

Returns “1” on success, “0” on failure.

)��9:9;

Prerequisites

The name field must refer to an existing CosAttribute.

Implementation

Calls IM_DeleteCosAttribute().



Return Values


-��9:9;

Prerequisites

The name field must refer to an existing CosAttribute.

Implementation

Calls IM_UpdateCosAttribute().

Return Values


Example

my @attr_list = CosAttribute::ReadAll();my $attr = $attr_list[0] if defined(@attr_list);

### For fast lookup of attributes by name:my %attr_dict;foreach $attr (@attr_list) { $attr_dict{$attr->name()} = $attr;}$attr = $attr_dict{’basic’};

# .............................................................

my $attr = new CosAttribute( name => ′pref_favoriteColor′, rule => IM_ATTR_RULE_COS_OVERRIDES, syntax => IM_ATTR_SYNTAX_STRING);$attr->Create();

$attr->rule(IM_ATTR_RULE_ACCOUNT_OVERRIDES);$attr->Update();

$attr->Delete();

CosThe class Cos (Class of Service) has the following fields:

A new Cos object can be created this way:

my $cos = new Cos( name => ′basic′, serviceDef => {

name String

serviceDef Reference to associative array of Class of Service (COS) values

InterMail Perl API


pref_quotatotkb => ′10000’, pref_quotathreshold => ′80′, pref_pop => ′1′, pref_imap => ′1′, pref_intermanager => ′1′ });

Note: The value for the “serviceDef” field is a reference to an anonymous hash.

See the note under CosAttribute about upper-case characters in name fields.

The current values of the fields will be returned as a formatted string by the Dump() function.

The class Cos defines the following methods to access the InterMail facilities:

&��9:9;

Prerequisites

None. This is a class method, which must be run as follows:

my @name_list = Cos::ReadNames();

Implementation

Calls IM_ReadCosNames().

Return Values

Returns a list of names of Cos objects on success, undef on failure.

'��9:9;

Prerequisites

The name field must be defined and not already in use by a previous created Cos.

Implementation

Calls IM_CreateCos().

Return Values


&��9:9;

Prerequisites

The name field must refer to an existing Cos.



Implementation

Calls IM_ReadCos().

Return Values

The “serviceDef” field is set to the current state of the Cos. Returns “1” on success, “0” on failure.

��,��9:9��9;

Prerequisites

The name field must refer to an existing Cos. The attr_name argument must correspond to an existing CosAttribute, and attr_value must be defined.

Implementation

Calls IM_SetCosAttribute().

Return Values

Returns “1” on success, “0” on failure. The attribute is added to the set defined by the Cos if necessary, and the value is set accordingly.

-��,��9:9��9;

Prerequisites

The name field must refer to an existing Cos. The attr_name argument must correspond to an existing CosAttribute.

Implementation

Calls IM_UnsetCosAttribute().

Return Values

Returns “1” on success, “0” on failure. The attribute is removed from the set defined by the Cos.

)��9:9;

Prerequisites

The name field must refer to an existing Cos.

Calls IM_DeleteCos().

Return Values


Example

my @name_list = Cos::ReadNames();

InterMail Perl API


my $cos = new Cos(name => $name_list[0]);$cos->Read();

my %serviceDef = %{$cos->serviceDef()};my ($name, $value);while (($name, $value) = each %serviceDef) { print "Attribute \"$name\" has value \"$value\"\n";}# .............................................................my $serviceDef = { pref_quotaTotKb => ’10000’, pref_quotaBounceNotify => ’1’};$cos = new Cos(name => ’basic’, serviceDef => $serviceDef);$cos->Create();

$cos->SetAttribute(′pref_quotaTotKb′, ′0′);$cos->SetAttribute(′pref_smtp′, ′1′);$cos->UnsetAttribute(′pref_quotaBounceNotify′);$cos->Delete();

DomainThe class Domain has the following attributes (fields):

A new Domain object can be created this way:

$domain=new Domain( type => IM_DOMAIN_LOCAL, name => ′example.com′);

The current values of the fields will be returned as a formatted string by the Dump() function.

type Enumerated integer. Possible values are:

IM_DOMAIN_ NO_CHANGE,IM_DOMAIN_UNKNOWN,IM_DOMAIN_DELETED,IM_DOMAIN_LOCAL,IM_DOMAIN_NON_AUTH,IM_DOMAIN_REWRITE

name String

relayHost String

rewriteName String

wildcardAccount String



The class Domain defines the following methods to access the InterMail facilities (see Chapter 6 for the requirements to the parameters and parameter combinations for various operations):

��9:9 ��9;

Prerequisites

This is a class function that should not be invoked on a Domain object. Instead, use the following form:

my @domain_list = Domain::List($from, $till, $max);

All arguments must be specified, but from and till can be empty strings, indicating the lexically least and greatest domain names, respectively. The max argument should be a number.

Implementation

Calls IM_ReadDomains().

Return Values

Returns a list of names on success, undef on failure.

The domain names that are lexically greater than or equal to from, and lexically less than till, are returned in a list. If from is empty or undefined, there is no lower lexical bound on the match. If till is empty or undefined, there is no upper lexical bound on the match. The comparison with from is inclusive, while till is compared exclusively, meaning domain names that match till exactly will not be returned. At most max names will be returned, and domain names will be returned in lexically increasing order. If max is –1, then all matching domain names will be returned.

It is possible to iterate through all domains using code similar to the following:

my $max = 100;my $from = ′′; # Start at the lowest possible name.my $till = ′′; # Continue to the highest possible name.my @list;

while (@list = Domain::List($from, $till, $max)) { shift(@list) if $list[0] eq $from; # Skip first if we’ve seen it. last unless @list; # All done if list is now empty. my $name; foreach $name (@list) { print ″$domain\n″; # Print the domain name. } $from = pop(@list); # Get the next set of names.}

InterMail Perl API


��)��9:9�� 9;

Prerequisites

This is a class function that should not be invoked on a Domain object. Instead, use the following form:

my @subdomains = Domain::ListSubDomains($topDomain, $from, $till, $max);

All arguments must be specified, but from and till can be empty strings. The topDomain and max arguments must be defined, and max must be a number greater than zero.

Implementation

Calls IM_ReadSubDomains().

Return Values

Returns a list of domain names on success.

The domain names contained by topDomain that are lexically greater than “from” and lexically less than “till” are returned. If “from” is empty or undefined, there is no lower lexical bound on the match. If “till” is empty or undefined, there is no upper lexical bound on the match. Both “from” and “till” are exclusive bounds, meaning domain names that match either “from” or “till” exactly will not be returned. At most “max” names will be returned, and domain names will be returned in lexically increasing order.

It is possible to iterate through all the sub-domains contained by a domain using code similar to the following:

my $topdomain = ′example.com′;my $max = 100;my $from = ′′; # Start at the lowest possible name.my $till = ′′; # Continue to the highest possible name.my @list;

while (@list = Domain::ListSubDomains( $topdomain, $from, $till, $max)) { my $name; foreach $name (@list) { print ″$domain\n″; # Print the domain name. } $from = pop(@list); # Get the next set of names.}



'��9:9;

Prerequisites

The fields name must be defined and valid.

Implementation

Calls IM_CreateDomain().

Return Values


&��9:9;

Prerequisites

The field name must be defined and valid.

Implementation

Calls IM_ReadDomain().

Return Values


-��9:9;

Prerequisites


Implementation

Calls IM_UpdateDomain().

Return Values


For those fields of the Perl object that are defined, the values will be used to rewrite the values of the record in the InterMail database.

No modification to the fields of the object is done in the result of calling this method. Use Read() to update the fields after calling Update().

Note: When Update() specifies a wildcard account, the user must use only the local portion of the SMTP address.

InterMail Perl API


)��9:9;

Prerequisites


Implementation

Calls IM_DeleteDomain().

Return Values


Example

$domain = new Domain( type => IM_DOMAIN_LOCAL, name => ′example.com′,);

$domain->type(IM_DOMAIN_REWRITE);$domain->name(′ddd′);$domain->rewriteName(′eee′);print ′Domain Name: ′, $domain->name(), ″\n″;print $domain->Dump();

$domain->Create();print_status();if ($domain->Read()) { print $domain->Dump();}$domain->rewriteName(′drn_XXX′);$domain->Update();print_status();$domain->Delete();print_status();

AccountThe class Account has the following attributes (fields):

smtpAddress String (must be a valid RFC822 mail address)

popAddress String

mssHost String

smtpHost String

popHost String

emailIntID String (of decimal digits)



A new Account object can be created in the following manner:

$account=new Account( smtpAddress => ′[email protected]′, popAddress => ′johndoe′, mssHost => ′paris′, emailIntID => ′1000000019971117′, plainPassword => ′rosebud′, hash => IM_PWHASH_CLEAR, status => IM_ACSTATUS_ACTIVE, local => IM_DELIVERY_ENABLED, acCos => { pref_quotaTotKB => ′10000′, pref_quotaThreshold => ′95′ });

The class Account defines the following methods to access the InterMail facilities (see Chapter 6 for the requirements to the parameters and parameter combinations for various operations):

'��9:9;

Prerequisites

The fields smtpAddress and mssHost must be defined and valid; the field emailIntID must be set to an “integer-like” string (i.e. a string consisting of decimal digits only).

If the account is to be accessible via POP or IMAP, the plainPassword or password field must be set. If plainPassword is set, it specifies the desired password in plain text, and it takes precedence over password. Otherwise, password is

password String

plainPassword String. When the plainPassword parameter is specified and the hash function is set to something other than clear, the input password is encrypted in the client before it is sent to the Directory.

hash enum IM_PwHashType (see Chapter 6)

status enum IM_AcStatus (see Chapter 6)

local enum IM_LocalDelivery (see Chapter 6)

cosName String

acCos Reference to associative array of Class of Service (COS) values

resultCos Reference to associative array of Class of Service (COS) values (read-only)

InterMail Perl API


assumed to be encrypted as specified by hash. If hash is not set, it defaults to IM_PWHASH_CLEAR.

To create an account in proxy mode, specify a status of IM_ACSTATUS_PROXY, and define values for both smtpHost and popHost, but do not define mssHost. If the account is not in proxy mode, define mssHost, but do not define smtpHost or popHost.

Implementation

Calls IM_CreateAccount().

Return Values


If the call succeeds, an account record will be created in the directory, with the parameters specified by the fields of the Perl object, or, for non-mandatory fields (see Prerequisites above), set to default values.

&��9:9;

Prerequisites

One of the following fields must be defined: smtpAddress , popAddress, emailIntID. If more than one is set, the precedence follows the order shown. If plainPassword is set, the call is treated as an authentication request, and it will return an error if the password is incorrect.

Implementation

Calls IM_ReadAccount().

Return Values


If the call succeeds, all fields of the Perl object will be set from the InterMail Directory.

-��9:9;

Prerequisites

The field smtpAddress must be defined and valid.

Implementation

Calls IM_UpdateAccount().

Return Values


For those fields of the Perl object that are defined, the values will be used to rewrite the values of the record in the InterMail database. There are constraints on the values



of certain fields during an update that are described in the InterMail C API documentation.

For the acCos field, every key that is defined in the associative array will be used in the update. Keys that have an undefined value will result in the removal of the corresponding COS attribute from the account. Other keys will add or modify COS attributes to the account.


Generally, it is not recommended that the Update() function be applied to objects that have been Read().The problem is that every single field of the object is being updated, not just the fields changed after the Read(). Instead, create a separate object for the call to Update(), and set the fields needed to identify the object and the fields that need to be changed. For example:

$account=new Account(smtpAddress => "[email protected]");$account->Read();

$upaccount = new Account( smtpAddress => $account->smtpAddress(), mssHost => "mss2");$upaccount->Update();

This will work assuming that the account was not previously in proxy mode. If it was in proxy mode, you should change the status at the same time that you specify the mssHost, as follows:

$upaccount = new Account( smtpAddress => $account->smtpAddress(), status => IM_ACSTATUS_ACTIVE, mssHost => "mss2");$upaccount->Update();

-��,��9:9��9;

Prerequisites

The field smtpAddress of the object must be defined and valid. The newSmtpAddress argument must be of the form “name@domain”, where domain is a valid domain in the InterMail directory, and the combination of name and domain has not already been used by another account or alias to an account.

Implementation

Calls IM_UpdateAccountAddr().

Return Values


Only the primary SMTP address of the account is altered by this function.

InterMail Perl API


)��9:9;

Prerequisites


Implementation

Calls IM_DeleteAccount().

Return Values


'��,��9:9��9;

Prerequisites

The field smtpAddress must be defined and valid. The addr argument must be a valid e-mail address, ending with an “@” followed by a domain name that is defined in the InterMail Directory.

Implementation

Calls IM_CreateAlias();.

Return Values


)��,��9:9��9;

Prerequisites

The addr argument must refer to an existing alias for this account.

Implementation

Calls IM_DeleteAlias();.

Return Values


Note: The Account DeleteAlias method is not a member function. It is a class method. Therefore, it is not called with an Account object, but as in the following example: Account::DeleteAlias($alias);



&��,��9:9;

Prerequisites


Implementation

Calls IM_ReadAccountAliases().

Note: If the Perl variable $IM_ReadAccountAliases_master is true, then IM_ReadAccountAliases_master() is called instead. This function gets its results from the master database, which avoids an apparent inconsistency that occurs when the Directory cache does not immediately register changes resulting from a call to CreateAlias(). Use this feature with caution, since it can impact the performance of the InterMail Directory.

Return Values

On success returns the list of existing aliases for this account. If no aliases are found, or if IM_ReadAccountAliases() fails, an empty list is returned.

$addr = ′[email protected]′;$account->CreateAlias($addr);print_status();$IM_ReadAccountAliases_master = 1; # (see special note above)@read_aliases = $account->ReadAliases();if (@read_aliases) { print ″Found aliases: @read_aliases\n″;} else { print ″Found no aliases\n″; print_status();}Account::DeleteAlias($addr);

'��9:9��9;

Prerequisites

The field smtpAddress must be defined and valid. The addr argument must be a valid e-mail address, ending with an “@” followed by a domain name. The domain need not exist in the InterMail Directory. At least one forwarding address must exist for this account.

Implementation

Calls IM_CreateForward(addr);.

Return Values


InterMail Perl API


)��9:9��9;

Prerequisites

The field smtpAddress must be defined and valid. The addr argument must refer to an existing forwarding address for this account.

Implementation

Calls IM_DeleteForward(addr);

Return Values


&��9:9;

Prerequisites


Implementation

Calls IM_ReadAccountForwards().

Return Values

On success returns the list of existing forward addresses for this account. If no such addresses exist, or if IM_ReadAccountForwards() fails, an empty list is returned.

$addr=“[email protected]”;$account->CreateForward($addr);print_status();@read_forwards=$account->ReadForwards();if (@read_forwards) { print ″Found forwards: @read_forwards\n″;} else { print ″Found no forwards\n″; print_status();}$account->DeleteForward($addr);

Note: Although the methods to manipulate account aliases and forwards look very similar, there is a significant difference between them: DeleteAlias() is a class method, whereas DeleteForward() is an instance method.



��9:9;

Prerequisites

The field smtpAddress must be defined and valid. At least one forwarding address must exist for this account.

Implementation

Calls IM_EnableAccountForwards().

Return Values


)��9:9;

Prerequisites


Implementation

Calls IM_DisableAccountForwards().

Return Values


$account->EnableForwarding();...$account->DisableForwarding();

&��,��9:9;

Prerequisites


Implementation

Calls IM_ReadAlias().

Return Values


One field, smtpAddress is mandatory and it should be set to a meaningful SMTP address, which will be considered to be an alias by this method. If an account with this alias exists, the method will reset this field to the account's primary SMTP address. No other change to the account fields will be made -- no information will be passed back from the directory to the Perl object, except for the SMTP address, and no existing field will be cleared.

InterMail Perl API


&��/�69:9;

Prerequisites

The field popAddress must be defined and valid.

Implementation

Calls IM_ReadPOP3().

Return Values


One field, popAddress is mandatory and it should be set to a meaningful POP address. If an account with this POP address exists, the method will set the field smtpAddress to the account's primary SMTP address. No other change to the account fields will be made -- no information will be passed back from the directory to the Perl object except for the SMTP address and no existing field will be cleared.

# Alias and pop address for the account [email protected]$alias=“[email protected]”;$pop=“katze”;

$account=new Account(popAddress => “hound”);$account->ReadPOP3();# The fields will now be:# smtpAddress=>“[email protected]”, popAddress=>“hound”

$account->smtpAddress(“[email protected]”);

$account->ReadAlias();# The fields will be now:# smtpAddress=>“[email protected]”, popAddress=>“katze”

��9:9��<9 ��<9��<9��9;

Prerequisites

This function does not operate on an Account object, so it must be invoked as Account::List(…). The domain and max arguments must be defined and max must be greater than zero.

Implementation

Calls IM_ReadAccounts().

Return Values

Returns a list of SMTP addresses (“local” portion only) on success.

The SMTP addresses of accounts in domain that are lexically greater than from and lexically less than till are returned. If from is empty or undefined, there is no lower lexical bound on the match. If till is empty or undefined, there is no upper lexical bound on the match. Both from and till are exclusive bounds, meaning names that match either from or till exactly will not be returned. Only addresses that match the



specified domain exactly will be returned. At most max names will be returned, and names will be returned in lexically increasing order.

It is possible to iterate through all the names in a domain using code similar to the following:

my $domain = ′example.com′;my $max = 100;my $from = ′′; # Start at the lowest possible name.my $till = ′′; # Continue to the highest possible name.my @list;

while (@list = Account::List($domain, $from, $till, $max)) { my $name; foreach $name (@list) { print ″$name\@$domain\n″; # Print the full SMTP address. } $from = pop(@list); # Get the next set of up to $max names.}

"��(��9:9��<9��9;

Prerequisites

This function does not operate on an Account object, so it must be invoked as Account::HashPassword(…). The password and hashType arguments must be defined, and hashType must correspond to one of the IM_PWHASH* constants.

Implementation

Calls IM_HashPassword().

Return Values

Returns the specified password in hashed form according to hashType.

'(��*��9:9��<9��<9��9;

Prerequisites

This function does not operate on an Account object, so it must be invoked as Account::CheckPassword(…). The password, hashedPassword, and hashType arguments must be defined, and hashType must correspond to one of the IM_PWHASH* constants.

Implementation

Calls IM_CheckPassword().

Return Values

Returns 1 if password matches hashedPassword when hashed according to hashType.

InterMail Perl API


MailboxThe class Mailbox has the following attributes (fields):

Some Mailbox methods use an associated Account object, which need not refer to an existing InterMail account, although most of the time it will. The Mailbox methods will use various fields of the Account object, depending on the operation, such as emailIntID and mssHost. The caller must ensure that the necessary fields of the Account are properly initialized, either by calling Account::Read(), or by setting the fields directly.

This may be necessary with administrative mailboxes; they do not have an InterMail directory account associated with them. Still, to access such a mailbox, one needs to specify some information that makes sense only in connection with an account.

Thus the Mailbox constructor looks different than other SwCom::Mail constructors: it takes a single argument (not in the call-by-pairs fashion), which should be an Account object. But the constructor is “intelligent” enough be able to process the call with the call-by-pairs syntax, where the only argument that matters is the account one.

The sequence of steps in manipulating a Mailbox object should be therefore as follows:

$account= ... # an account to tie the mailbox to.$mailbox = new Mailbox($account);

# Or use the alternative syntax:# $mailbox = new Mailbox(account => $account);

Make sure that the required fields of the $account are set prior to invoking functions on a Mailbox.

This will set the mailbox's name field to the “owning” account's emailIntID, and its host field to the account's mssHost value.

Note that the only “active” field of a Mailbox object is account—although all the rest can be set by a user, this will have no influence on any operation on the object.

account Reference to an Account object

name String (of decimal digits). Field is the same as emailIntID except for administrative accounts

host String

msgsStored Integer (read-only)

bytesStored Integer (read-only)

inbox String



Instead, those fields will be set to the “real” values as a result of invoking a method of the class.

This how you could start working with a “real” account:

# Construct an account object without specifying# any information but the ″key″:$account=new Account(smtpAddress=>“[email protected]”);

# Get the account data from InterMail database:$account->Read(); # sets emailIntID, host, quotas etc # Construct a mailbox object:$mailbox=new Mailbox($account);

# Notice that $mailbox”s fields, other than “account”,# are undefined yet:print $mailbox->name(); # prints ″″print $mailbox->host(); # prints ″″

if (want_create()) { # Create a ″real″ mailbox: $mailbox->Create();} else { # will read an existing mailbox data $mailbox->Read();}

# $mailbox”s fields have meaningful values now:print $mailbox->name(); # prints ″1234567890″ print $mailbox->host(); # prints ″lost″

And this is how you could deal with a “fake” account (this could also be an alternative, “shortcut” way to construct a mailbox):

# Construct a mailbox object:$mailbox=new Mailbox(new Account( # This is as if we had set the mailbox”s name and host directly: emailIntID=>“1234567890”, mssHost=>“lost”));

$mailbox->Read();

# $mailbox”s fields have meaningful values now:print $mailbox->name(); # prints ″1234567890″ print $mailbox->host(); # prints ″lost″

The class Mailbox defines the following methods to access the InterMail facilities (see Chapter 6 for the requirements to the parameters and parameter combinations for various operations):

InterMail Perl API


'��9:9��9;

Prerequisites

The account field must reference a valid Account object, with emailIntID and mssHost set.

Implementation

Calls IM_CreateMailbox().

Return Values


Creates a mailbox and, optionally, inserts a message identified by messageId. If the second argument is absent or is the string ″none″, no message will be put in the newly created mailbox.

If the call is successful, fills in the fields of the object.

&��9:9;

Prerequisites

The account field must reference a valid Account object, with the emailIntID and mssHost fields set.

Implementation

Calls IM_ReadMailbox().

Return Values


If successful, the method fills in all the fields of the object; the name field will be set to the “owning” account's emailIntID and the host field to the account's mssHost field.

)��9:9;

Prerequisites

The account field must reference a valid Account object, with the emailIntID and mssHost fields set.

Implementation

Calls IM_DeleteMailbox().

Return Values


Deletes the mailbox record in the InterMail database.



Example

# Construct an account object without specifying# any information but the ″key″:$account=new Account(smtpAddress=>“[email protected]”);

# Get the account data from InterMail database:$account->Read(); # sets emailIntID. host, etc

# Construct a mailbox object:$mailbox=new Mailbox($account);

# Create a ″real″ mailbox:$mailbox->Create();print_status();

if ($mailbox->Read()) { print $mailbox->Dump();}print_status();

$mailbox->Delete()print_status();

Notes

The need to create a “fake” account may arise for administrative mailboxes. These administrative accounts do not have an SMTP address, therefore, the only way to refer to them is by specifying the host where they (their mailboxes) reside, and their emailIntID.

The emailIntID of a fake account does not have to be a string of decimal digits, as required for real accounts. As a matter of fact, it will usually be something like ″admin″

One will probably not use SwCom::Mail to create or delete administrative mailboxes -- there are special InterMail tools to do it. The only operations normally required for these special mailboxes would be adding and removing messages and folders.

An even more likely scenario of working with an administrative mailbox is to invoke the Read() method just to “synchronize” the Perl object with the InterMail database record. After invoking the Read() method, the Mailbox object can be used to access the mailbox's folders and messages.

A typical example of using a Mailbox object to access administrative data is as follows:

# Note that we do not use the account SMTP address, but# rather its emailIntID, which is quite a different thing:$mailbox = new Mailbox(

new Account(emailIntID => ″admin″, mssHost => ″paris″));$mailbox->Read();

# $mailbox”s fields have meaningful values now:print $mailbox->name(); # prints ″admin″

InterMail Perl API


print $mailbox->host(); # prints ″paris″print $mailbox->inbox(); # prints ″crate″

# But the really interesting information is inside folders:$folder = new Folder( mailbox => $mailbox, pathname => ′/rumors′,);

# One can work with the folder now:$folder->Read();

��'��0�9:9��9;

Prerequisites

The size argument must be a number greater than or equal to zero.

Implementation

Calls IM_SetMSSConnPoolSize().

Return Values

None.

This function sets the size of the MSS connection pool. The default size is 0, meaning no caching is done. If the connection pool size is set to “n”, then the last “n” connections made to an MSS will be cached.

When using a Mailbox, if the underlying C-API needs to make a connection to an MSS, it will check its connection pool first to see if there is an existing connection available. If one is available, it will use it, otherwise it will make a new one.

When an IM_Mbox is destroyed, the MSS connection associated with it (if any) is placed in the pool, unless that would cause the size of the pool to exceed the maximum specified by this function, in which case the connection is destroyed.

FolderThe class Folder has the following attributes (fields):

mailbox Reference to a Mailbox object

pathname String

folders Reference to an array of strings (names of subfolders)

messages Reference to an array of Message objects

readOnly integer

clearRecent integer



A new Folder object can be created in one of two ways:

1. By specifying the mailbox it belongs to and the full “path” to this folder:

$mailbox = ... # get a reference to an existing mailbox.$folder = new Folder( mailbox => $mailbox, pathname => ′/folder_1/folder_2′);

2. By specifying the folder's parent, be it a mailbox (for the top-level folders) or another folder, and a relative pathname from the parent:

$folder_f1 = new Folder(parent => $mailbox, name => ′f1′);$folder_f1_f2 = new Folder(parent => $folder_1, name => ′f2′);

When the constructor is invoked this way, the mailbox and pathname fields are built on the fly, using the parent’s information.

The current values of the fields can be printed on the standard output stream as follows:

print $folder->Dump();

The class Folder defines the following methods to access the InterMail facilities (see Chapter 6 for the requirements to the parameters and parameter combinations for various operations):

'��9:9;

Prerequisites

The mailbox and pathname fields must be defined and valid.

Implementation

Calls IM_CreateFolder().

Return Values


&��9:9;

Prerequisites


Implementation

Calls IM_ReadFolder().

Return Values


UIDValidity integer

InterMail Perl API


On successful return from this function:

1. The field folders will be a reference to an array of strings—names of this folder's subfolders.

2. The field messages will be a reference to an array of Message objects. The information contained in the elements of this array will be incomplete—only the fields msgRef, msgId and size will be filled in. Use the Message::Read() function to retrieve all the data for a specific message.

&��9:9��9;

Prerequisites


Implementation

Calls IM_RenameFolder().

Return Values


Renames the folder to the new_name.

)��9:9;

Prerequisites


Implementation

Calls IM_RenameFolder().

Return Values


)��9:9��9;

Prerequisites


Implementation

Calls IM_DeleteFolderMsgs().

Return Values


Deletes one or more messages from a folder. One or more Message objects (from the Folder’s messages array) should be passed as arguments. It is also possible to pass an



array of Messages instead of individual Messages. This function is more efficient than deleting the messages one by one.

��9:9��<9=9;

Prerequisites


Implementation

Calls IM_ScanFolderMsgs().

Return Values


Scans the headers of one or more messages in a folder so that future calls to ReadHeader() will be faster. One or more messages (from the folder’s messages array) should be passed as arguments. It is also possible to pass an array of messages instead of individual messages. This function is useful when the caller needs to look at the headers of a large number of messages; it is more efficient to load the headers with this one call than to have them loaded one by one.

Example

$mailbox = ... # get a reference to an existing mailbox.$folder_f1 = new Folder(parent => $mailbox, name => ′f1′);$folder_f1_f2 = new Folder(parent => $folder_f1, name => ′f2′);

$folder_f1->Create();print_status();$folder_f1_f2->Create()print_status();

$folder_f1->Read();print_status();print $folder_f1->Dump();

print ″Dumping subfolders:\n″;foreach $foldername (@{$folder_f1->folders()}) { print ″$foldername\n″;}

print ″Dumping messages:\n″;foreach $msg (@{$folder_f1->messages()}) { print $msg->Dump(), ″\n″;

# or do it field by field: # my $id = $msg->msgId(); # my $size = $msg->size(); # my $msgRef = $msg->msgRef(); # print ″id=$id, size=$size, msgRef=$msgRef\n″;}

$folder_f1_f2->Rename(′/f1/f2a′);

InterMail Perl API


print_status();print $folder_f1_f2->Dump();$folder_f1_f2->Delete();

��9:9�� <9��!� �<9=9;

Prerequisites

The mailbox and pathname fields must be defined and valid. The dstFolder argument must be a reference to another Folder in the same Mailbox as the Folder on which this function is invoked.

Implementation

Calls IM_MoveMsgs().

Return Values


Moves messages from a folder to another folder. One or more msgRefs (from the Message objects in the Folder’s messages array) should be passed as arguments. It is also possible to pass an array of msgRefs instead of individual msgRefs.

'��9:9�� <9��!� �<9=9;

Prerequisites

The mailbox and pathname fields must be defined and valid. The dstFolder argument must be a reference to another Folder in the same Mailbox as the Folder on which this function is invoked.

Implementation

Calls IM_CopyMsgs().

Return Values


Copies messages from a folder to another folder. One or more msgRefs (from the Message objects in the Folder’s messages array) should be passed as arguments. It is also possible to pass an array of msgRefs instead of individual msgRefs.

MessageThe class Message has the following attributes (fields):

mailbox Reference to a Mailbox object

folder Reference to a Folder object

msgRef Integer



The Message constructor requires a reference to the Folder object that contains the message, either as a single argument:

$folder = ... # get a reference to an existing folder.$message = new Message($folder);

or through the call-by-pairs syntax:

$folder = ... # get a reference to an existing folder.$message = new Message(folder => $folder);

The field mailbox will be set by the constructor to point to the Mailbox where the folder resides, and should not be set directly by the client code.

The class Message defines the following methods to access the InterMail facilities (see Chapter 6 for the requirements to the parameters and parameter combinations for various operations):

'��9:9 ��<9��9;

Prerequisites

The mailbox and folder fields must be defined and valid. The “from” and “text” arguments must be specified, and text must be formatted according to RFC822.

Implementation

Calls IM_CreateMsg().

Return Values


If the call is successful fills in the field msgRef.

msgId String

size Integer

seen Integer

arrivalTime Integer

arrivalTimeString String

UID Integer

flags String

InterMail Perl API


&��9:9;

Prerequisites

The mailbox, folder and msgRef fields must be defined and valid.

Implementation

Calls IM_ReadMsg().

Return Values


Fills in the values of all fields of the object by retrieving the information from the InterMail database.

&��"��9:9 ��9;

Prerequisites


Implementation

Calls IM_ReadMsgHeader().

Return Values

If the call is successful (in particular, the requested field should exist in this message), the body of the field is returned, as a string. Otherwise, the undef value is returned.

&��'��9:9� ��<9��9;

Prerequisites


Implementation

Calls IM_ReadMsgBody().

Return Values

If the call is successful, the requested chunk of the text of the message (which includes “headers” is returned, as a string. Otherwise, the undef value is returned.

)��9:9;

Prerequisites


Implementation

Calls IM_DeleteMsg().



Return Values


-��9:9 ��9;

Prerequisites


Implementation

Calls IM_UpdateMsgFlags().

Return Values


Updates the message flags of a message. The flags argument is a string of characters which specify which flags to change. Each character position represents a flag; a 'T' character sets the flag, a 'F' character clears it, and a '-' character leaves it alone. This string must be no longer than 6 characters; if may be shorter if only the first few flags need to be changed.

Example

$folder = ... # get a reference to an existing folder.$message = new Message(folder => $folder);$from = “[email protected]”;$text = <<′EndOfMessage′From: catTo: mouse

Care to join me for dinner?EndOfMessage

$folder->Read();print $folder->Dump(); # lists messages (list_1)$message->Create($from, $text);$folder->Read();print $folder->Dump(); # lists messages (list_2)

# All operations on messages, except for “Create()”,$message->msgRef(123);$message->Read();print $message->Dump();

$headertext = $message->ReadHeader(′from′);print ″Field \″from\″: \″$headertext\″\n″ if $headertext;

$bodytext = $message->ReadContent(0, 64);print ″Text: \″$bodytext\″\n″ if $bodytext;$message->Delete();

InterMail Perl API


ReplyThe class Reply has the following attributes (fields):

A new Reply object can be created this way:

$account = ... # get a reference to an existing account.$reply = new Reply( account => $account, mode => IM_REPLY_VACATION, host => ′hostess′, text => ′I will call you...′);

'��9:9;

Prerequisites

All the fields must be defined and valid. The account field must reference a Perl object with a correctly set emailIntID field.

Implementation

Calls IM_CreateReply().

Return Values


account Reference to an Account object

mode The type of reply, which are:

IM_REPLY_NONE = ‘N’

IM_REPLY_AUTO = ‘R’

IM_REPLY_ECHO = ‘E’

IM_REPLY_VACATION = ‘V’

msgRef Integer

host String

text String

type A Software.Com or user-defined integer. Positive integers indicate Software.Com reply types, whereas negative integer indicate user-defined reply types.



&��9:9;

Prerequisites

The field account must be defined and valid. The account field must reference a Perl object with a correctly set emailIntID field.

Implementation

Calls IM_ReadReply().

Return Values


-��9:9;

Prerequisites

The field account must be defined and valid. The account field must reference a Perl object with a correctly set emailIntID field.

Implementation

Calls IM_UpdateReply().

Return Values


For those fields of the Perl object that are defined, the values will be used to rewrite the values of the record in the InterMail database.


)��9:9;

Prerequisites

The field account must be defined and valid.

Implementation

Calls IM_DeleteReply().

Return Values


Example

$account = ... # get a reference to an existing account.$reply = new Reply( account => $account, mode => IM_REPLY_VACATION, host => ′hostess′, text => ′I will be gone all week.′

InterMail Perl API


);

print ′Reply Text: ′, $reply->text(), ″\n″;print $reply->Dump();$reply->Create();print_status();if ($reply->Read()) { print $reply->Dump();}$reply->text(′I am never coming back.′);$reply->Update();print_status();$reply->Delete();

Notes

There is an interesting difference between the class Reply and the rest of SwCom::Mail classes. For the latter ones, an InterMail record does not exist until one invokes the method Create() on an object of the class. The Reply class is different because it is essentially an attribute of an Account, and all accounts have an auto-reply state, even if no Reply object has ever been created for them. An account’s auto-reply type defaults to IM_REPLY_NONE, therefore Reply::Read() will always succeed for Reply objects that refer to existing InterMail accounts (except for internal InterMail errors). Be careful not to invoke the method Read() on a Reply object if you intend to call Create() afterwards: Read() will change the Perl object even when “there was no auto-reply” for the account.

ConfigItemThe class ConfigItem has the following attributes (fields):

A new ConfigItem object can be created this way:

$config = new ConfigItem( name => ’netTimeout’, host => ’paris’, prog => ’mta’, defvalue => ′60′);

name String

host String

prog String

defvalue String

value String



&��9:9;

Prerequisites

The name field must be set.

Implementation

Calls IM_ReadConfig().

Return Values


MimeInfoThe class MimeInfo has the following attributes (fields):

isMultiPart Integer

isMessagePart Integer

childCount Integer

headerOffset Integer

bodyOffset Integer

headerLength Integer

totalSize Integer

numLines Integer

contentTransferEncoding String

mainContentType String

subContentType String

contentID String

contentDescription String

boundary String

contentMD5 String

contentDisposition String

contentLanguage Array of strings

InterMail Perl API


&��9:9��<9>��<9>��??;

Prerequisites

Note: This is a member function of the Message class, not the MimeInfo class. See the sample code below.

The mime argument must be defined and valid. The parent argument is optional; if present, it must be defined and valid and point to a MimeInfo object describing a multipart or message/rfc822 message. If it points to a multipart, the index argument must be present and must be defined and valid.

Implementation

Calls IM_ReadMimeInfo().

Return Values


The following is a sample piece of code that dumps a message's MIME tree:

# Load the message $message = new Message(folder=>..., msgref=>...); $message->Read(); $mime = new MimeInfo; $message->ReadMimeInfo($mime); dumpit(’toplevel’, $message, $mime);

sub dumpit { my ($id, $message, $mime) = @_; print "==================================\n"; print "$id\n"; print $mime->Dump(), "\n"; if ($mime->{isMessagePart}) { $cmime = new MimeInfo; $message->ReadMimeInfo($cmime, $mime); dumpit($id . ’.body’, $message, $cmime); } elsif ($mime->{isMultiPart}) { $cmime = new MimeInfo; my $i; for ($i = 0; $i != $mime->{childCount}; $i++) { $message->ReadMimeInfo($cmime, $mime, $i); dumpit($id . ’.’ . $i, $message, $cmime); } } }

parameters Array of strings



LogMsgObjects of type LogMsg have the following attributes:

A new LogMsg object can be created this way:

$logmsg = new LogMsg( severity => IM_SEVERITY_ERROR, type => ′FioCreateFail′, args => [ $filename ]);

'��9:9;

Prerequisites

logName must be set to a valid filename containing no “/” characters. Other attributes are ignored.

Implementation

Calls IM_CreateLogFile().

Return Values


+��9:9;

Prerequisites

Either msgID or type must be set, and severity must be set. The args and logName attributes are used if set.

Implementation

Calls IM_WriteLogMsg().

Return Values


severity enum IM_Severity

msgId Integer referring to a valid InterMail error number (e.g. 0x490013)

type String referring to a valid InterMail error mnemonic, e.g. ′NioConnTimeout

args Reference to an array of strings

text String

logName String

InterMail Perl API


This function can be used as a member function or a class function. When invoked as a member function on a LogMsg object, it uses the attributes stored in the object, for example:

$logmsg = new LogMsg(severity => IM_SEVERITY_ERROR, type => ′FioCreateFail′, args => [ $filename ]);$logmsg->Write();

Often there is no need for the LogMsg object beyond the creation of the log file entry, so we support a shortcut that accomplishes the same action as the previous code in a single statement:

LogMsg::Write(severity => IM_SEVERITY_ERROR, type => ′FioCreateFail′, args => [ $filename ]);

&��$�!�9:9;

Prerequisites

Either msgID or type must be set, and severity must be set. The args attribute is used if set.

Implementation

Calls IM_ReadLogMsgText().

Return Values

Returns “1” on success, “0” on failure. The text attribute is filled in with the text that would be used in a log file entry (without the leading timestamp and process information).

LogContextObjects of type LogContext have the following attributes:

mailUser String: an SMTP address or POP login name

mailHost String: logical hostname for an MSS machine

mailbox String of decimal digits

from String: an SMTP address

folder String: pathname to a folder in a mailbox

msgId String: contents of the Message-ID header in an RFC822 message

origMsgId String: contents of the Message-ID header in an RFC822 message before it was modified by the MSS



A new LogContext object can be created this way:

$logmsg = new LogContext( mailUser => $userName, folder => $folderName, cmd => $commandName);

-��9:9;

Prerequisites

None.

Implementation

Calls IM_UpdateLogContext().

Return Values


The current values in the LogContext object will be saved in the global logging context for use when generating log file entries. Missing or empty attributes will cause those values to be omitted from log file entries.

&��9:9;

Prerequisites

None.

Implementation

Calls IM_ReadLogContext().

Return Values


The values from the global logging context will be stored into the LogContext object, replacing any values that were previously stored there.

size Integer: size of an RFC822 message in bytes

cmd String: identifies the current operation

destHost String: logical hostname for an MSS machine

fromHost String: logical hostname for an MSS machine

port Integer: port number used to connect to an MSS


7InterManager Perl API

This chapter describes the InterManager Perl API that is used to support the InterManager Web interface as well as support the batch-load utility, which provisions InterManager data. This chapter includes the following information:

• An overview of classes used by the InterManager Perl API.

• Descriptions of the InterManager Perl API classes.

IntroductionThe InterManager Perl API provides an object-oriented interface to the data that can be manipulated by Software.com’s InterManager product. This includes LDAP and InterMail Directory information about organizations, people, and e-mail accounts.

Note: To maintain compatibility with the InterMail Perl API, the original attribute names set upon objects are recognized (e.g., smtpAddress for the Account object and so forth). Note that the object Read() methods will only return InterManager style attribute names. (These are currently all in lower case.)

Please read the Intermail Perl API’s “Introduction” on page 393 in this manual for introductory material about using the InterMail Perl APIs. This section will provide you with some general usage notes and other useful information about executing a Perl script.

Overview of ClassesThis table should give you a quick overview of the classes used by the library. Indentation shows class inheritance. Those marked with ‘*’ are internal to the API implementation.

SwCom::Error Access to errors

SwCom::WebSession A WWW session



InterManager Perl API ClassesThe following sections describe the individual API classes contained in the InterManager Perl API.

SwCom::ErrorDescription

Provides access to InterManager errors. The SwCom::Error class contains information about why an operation was unsuccessful.

Synopsis

my $err = new SwCom::Error($type, $number, $string);print $err->Type();print $err->String();die if ($err->Number() > 5);my $err2 = new_from_error SwCom::Error($err);

Methods

• new SwCom::Error(type, number, string)Constructor for the Error object. Initializes the Error object with the supplied argu-ments. Returns a reference to a SwCom::Error object.

• new_from_error SwCom::Error(Error)Constructor for the Error object. Returns a reference to a SwCom::Error object. Constructs a new Error object from the given Error object.

SwCom::IMgr::Session An LDAP session

SwCom::IMgr::Entry Base class for LDAP entries

SwCom::IMgr::Root LDAP Root

SwCom::IMgr::Org LDAP Organization

SwCom::IMgr::OrgUnit LDAP Organization Unit

SwCom::IMgr::Person LDAP Person

SwCom::IMgr::MailGroup Mail Group

SwCom::IMgr::MailTemplate Mail Template

SwCom::IMgr::MailCOS Class Of Service

SwCom::IMgr::Provider Mail Service Provider

SwCom::IMgr::AdminGroup* Administrative Group

SwCom::IMgr::Domain InterManager Domain Name object

InterManager Perl API


• Type()This method returns a string describing the source of the error, thus allowing for overlapping error numbers. Valid types are: ’LDAP’, ’IM’.

• String()This method returns a string describing the error.

• Number()This method returns an error id number.

SwCom::WebSessionDescription

Manages WWW administration sessions. The SwCom::WebSession class provides functions for managing WWW administrative sessions. After a session is created, it is identified by a unique token that gets passed from HTTP request to HTTP request. These tokens are time sensitive and can either expire, or be explicitly killed with the Delete() method.

Synopsis

$ws = new SwCom::WebSession; die unless $ws->Create($ipaddr, $login, $passwd, $md5passwd); die unless $ws->Validate($ipaddr, $token); $token = $ws->GetToken(); if ($ws->Delete()) { print "Log out successful"; } $ldap_session = $ws->GetLDAPSession(); $err = $ws->GetError(); $ws->SetError($err);

Methods

• new SwCom::WebSession()SwCom::WebSession constructor. Returns a reference to a new WebSession object.

• Create($ipaddr, $login, $password, $md5passwd)Method used to authenticate a new user and activate a new Web Session for the user. It sets up an SwCom::IMgr::Session object representing the active Web Session. If $password is defined, the user is authenticated by comparing the plain text password stored in their account. If the $md5passwd is defined, the user is authenticated by comparing the hashed password value read from their account. Both may be supplied. Returns 1 if successful, 0 otherwise.

• Update()Modifies the values persisted for the active SwCom::WebSession object. The values are stored in a hash upon the object. The valid keys are token, ipaddr, login, passwd, encpasswd, smtpAddress, popAddress, mssHost, email-IntID, and services. If the key ‘token’ is undefined, a new token will be calcu-lated and stored for the active session. The service is a hash of key/value pairs, where each key is a valid Class of Service attribute.

Returns 1 if successful.



• Validate($ipaddr, $token)This method verifies that a given token exists and has not timed out. It sets up an SwCom::IMgr::WebSession object for the active session identified by the token.

Returns a new SwCom::IMgr::WebSession object if successful, 0 otherwise.

• GetToken()Returns a unique ASCII string that identifies the WebSession. This string must be passed in every HTTP request of a web session.

• Delete()This method is used to explicitly end a running WebSession. The token identified with the Web session is invalidated. The LDAP session is closed (if necessary) by “unbinding” the user. This function is useful for implementing 'logout' buttons.

Returns 1 on success, 0 otherwise.

• GetLDAPSession()This method returns a reference to a SwCom::IMgr::Session object. This ref-erence can be used to construct objects derived from SwCom::IMgr::Entry.

• GetError()Returns a reference to a SwCom::Error object that describes the reason for most recent failed operation. Not reset on success.

• SetError($err) | SetError (type, number, string)Sets the Error object within the WebSession object. Input could either be an Error object or error type, number and string.

SwCom::IMgr::Session Description

Manages LDAP sessions. This class provides a few simple methods for managing LDAP sessions within the InterManager API. Normally, the WebSession class will manage the creation of a SwCom::IMgr::Session object.

Synopsis

$ldap_session = new SwCom::IMgr::Session($ldap_host, $login, $passwd);$ld = $ldap_session->Connect();$ld = $ldap_session->Bind();$ld = $ldap_session->RootBind();$ldap_session->Unbind();$ldap_session->Log($text);$ldap_session->SetErrorDst($objref);$ldap_session->SaveError(errtype, errnum, errstr);$ldap_session->SaveLDAPError($err);my $err_num = $ldap_session->GetLDAPError();my $err = $ldap_session->GetError();



Methods

• new SwCom::IMgr::Session(ldap_host, login, passwd)Returns a reference to a new SwCom::IMgr::Session object. The user of the session is identified via the login and passwd parameters. These are identical to those supplied in SwCom::WebSession::Create(). See SwCom::WebSes-sion::GetLDAPSession()

• Connect()Opens a connection to the LDAP server if one is not already open for the current Web session. Saves the LDAP session descriptor in the current object. The LDAP session descriptor is often used when constructing InterManager objects that are written to the DIT. This function is called automatically by Bind()

Returns an LDAP session descriptor on success, otherwise undef.

• Bind()Binds to the LDAP server using the login and password supplied to the construc-tor. Returns the LDAP session descriptor on success, otherwise undef.

• RootBind()Binds to the LDAP server as “Root”. Returns the LDAP session descriptor on suc-cess, undef otherwise.

• Unbind()Unbinds from the LDAP host. Returns 1 on success, 0 otherwise. See SwCom::WebSession::Delete().

• SetErrorDst (ErrorDst)Stores a reference to an object, whereto all errors are to be sent. ErrorDst is a ref-erence to the recipient object and it must implement the GetError() SetEr-ror() methods. (See WebSession::GetError() and WebSession::SetError()). Prior to storing the new object reference, the Set-Error() method is called upon it to verify it works.

Returns the old Error object.

Note: The destination object is initially the SwCom::IMgr::WebSession object that created the current LDAP session object. The WebSession will in turn store errors it receives in a SwCom::Error object.

• SaveLDAPError(err)Saves the supplied LDAP error code in the current object and sets the error type to ‘LDAP’. Sets the error in the error destination object if there is one. See SwCom::IMgr::Session::SetErrorDst(). Calls SwCom::IMgr::Ses-sion::Log() to print the error string to STDERR. Does not return anything.

• GetLDAPError()Returns the error number stored in the Session object.

Note: It does not matter if the error code is and LDAP error or not.



• SaveError($err) | SaveError(type, number, string)Saves the supplied error within the current Session object. Sets the error in the error destination object if there is one. See SwCom::IMgr::Session::SetEr-rorDst(). Calls SwCom::IMgr::Session::Log() to print the error string to STDERR. Does not return anything.

• GetError()Returns the Error object from the Session object.

• Log(text)Prints the text message along with the localtime to STDERR.

SwCom::IMgr::Entry Description

Generic class for LDAP entries. A foundation class implementing common methods and utilities used by most objects that are written as LDAP entries. Objects of type SwCom::IMgr::Entry should not normally be created, except during the constructor of a derived class.

In most cases, the behavior of a particular LDAP entry is determined by its attributes. The InterManager API provides access to attributes, and it is possible to do quite a lot with the generic Create, Read, Add, SetAttributes, Remove, Update, and Delete operations. There are very few calls in this API designed to access or control a specific attribute.

Detailed information about LDAP attributes entries and hierarchies are present in the DIT documentation.

Attempts to use entries or attributes in a manner that contradicts the InterManager DIT, or to access entries or attributes without the necessary access privileges, will be rejected by the API.

Synopsis

my $entry = new SwCom::IMgr::Entry($class, $imgrSession, $dn);my $parent = $entry->GetParent();my $dn = $entry->GetDN();my $parent_dn = $entry->GetParentDN ();my $org = $entry->Org();return undef unless $entry->Create({attr1 => [$a1v1, a1v2, ...], ...});print "Entry Deleted" if ($entry->Delete());print "Entry updated" if ($entry->Update(\%attrs));my %attrs = %{$entry->Read( [attr1, attr2, ...] )};return undef unless $entry->Rename($new_rdn, $delete_old_rdn);return undef unless $entry->ChangeDN($dn);

my $domain = SwCom::IMgr::Entry::DNToDomain($dn);my $dn = SwCom::IMgr::Entry::DomainToDN:: ($domain_name);my $domain_dn = SwCom::IMgr::Entry::DNToDomainDN($dn);



return $this->_LDAPError($ld);

Methods

• new SwCom::IMgr::Entry(IMgrSession, dn);Constructor for SwCom::IMgr::Entry. Returns a reference to a SwCom::IMgr::Entry object. This method is not normally used outside the Inter-Manager API.

• GetDN()Returns the distinguished name (DN) of the LDAP entry. Call this routine using its fully qualified name.

• GetParentDN()Returns DN of the parent LDAPentry. Call this routine using its fully qualified name.

• GetParent()Constructs parent’s entry from the parent’s DN. Returns the parent SwCom::IMgr::Entry object.

• DNToDomain(dn)Extracts the domain name from the DN. Presumes the dn is of an entry residing under an Organization within the DIT. The primary domain name is used to con-struct the Organization’s DN. It is that primary domain name that is extracted by this routine. Returns a domain name. Do not pass a $self pointer to this rou-tine. Call this routine using its fully qualified name. For example,. if DN is:

[email protected],ou=engg,dc=venus,dc=software,dc=com

it returns “venus.software.com”.

• DomainToDN(domain_name)Constructs the DN from the complete domain name. Do not pass a $self pointer to this routine. Call this routine using its fully qualified name. Returns a DN. For example, if domain_name is:

venus.software.com,”

it returns “dc=venus,dc=software,dc=com.”

• DNToDomainDN(dn)Extracts the DN that comprises only “dc=“ relative DN (RDN) components. Do not pass a $self pointer to this routine. Call this routine using its fully qualified name. Returns a DN. For example, if DN is:

[email protected],ou=engg,dc=venus,dc=software,dc=com

it returns “dc=venus,dc=software,dc=com”.

• Org()For Entries residing within an Organization, returns a reference to their SwCom::IMgr::Org object.

• Create(attr1 => [a1v1, a1v2, ...], ...)Creates the LDAP entry in the directory. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on



success, undef otherwise.

• Delete()Deletes the LDAP entry from the directory. Returns 1 on success, undef otherwise.

• Add(attr1 => [a1v1, a1v2, ...], …)Adds the specified attributes to the LDAP entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

• Remove(attr1 => [a1v1, a1v2, ...], …)Removes the specified attributes from the entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

• SetAttributes(attr1 => [a1v1, a1v2, ...], …)Sets the attributes (keys of hash) to the specified values in the entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

• Update(attr1 => {op => [a1v1, a1v2, ...]]}, ...)Updates the LDAP entry using the passed attr/value-array pairs. If exactly one argument follows self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. The op key in the second hash above may be: ‘a’, 'd', or ‘r’, repre-senting “add”, “delete”, or “replace” respectively. This method is not intended to be called. Use instead the Add, Remove, and SetAttributes methods. They are implemented in terms of the Update method. Returns 1 on success, undef other-wise.

To replace all attribute values, use the following form:

{attr1 => {’r’ => [a1v1, a1v2, ...]}, ...}

To add new attribute values:

{attr1 => {’a’ => [a1v1, a1v2, ...]}, ...}

To remove select attribute values:

{attr1 => {’d’ => [a1v1, a1v2, ...]}, ...}

Example set of mixed operations:

{ oldbooks => {’d’ => [’Horton Hears a Who’, ’The Bird Snatcher’]}, newbooks => {’a’ => [’Green Eggs and Ham’]}, library => {’r’ => [’0002’, ’0003’, ’0004’]}, }

• Read ( attr1, attr2, ... )Reads the LDAP entry returning its attr/value-array pairs in a hash reference. The attribute list is optional. If used, only specified attributes are retrieved from the



entry. Otherwise, all attributes are retrieved.

Note: As attributes may be multi-valued, the returned hash stores the attribute values as arrays (even single valued attributes). Any attributes read that don’t yet have values on the LDAP entry are a valid key in the returned hash, mapped to the undef value. In case of error, it returns undef.

• Rename (new_rdn, delete_old_rdn=1)Functionally equivalent to the ldap_modrdn() function, this routine alters the most specific component of the object’s DN. The $delete_old_rdn flag is optional. If it evaluates to TRUE, the old RDN attribute value is deleted. If it is not specified, it defaults to TRUE. Returns 1 on success, undef otherwise.

• ChangeDN ($new_dn)It is functionally equivalent to the ldap_rename() function. The entry’s DN is changed to the new DN. The entry must be a leaf in the DIT. Returns 1 on success, undef otherwise.

SwCom::IMgr::Root Description

The LDAP root. A way to specify the LDAP root (DN = “”) for functions that accept LDAP entry arguments. There are no valid operations on the LDAP root itself.

Note: As all methods that take a DN as parameter allow root to be specified as “”, there has been no use of this object. )

Synopsis

$ldap_top = new SwCom::IMgr::Root(IMgrSession);

Methods

• new SwCom::IMgr::Root(IMgrSession);Constructor for IMgr::Root. Returns a reference to a SwCom::IMgr::Root object. See also SwCom::IMgr::Entry.

SwCom::IMgr::Org Description

LDAP Organizations. This object corresponds to an LDAP entry that represents the top level of an organization.

Synopsis

$org = new SwCom::IMgr::Org(IMgrSession, $o_name, $domain_name);$org = new_from_dn SwCom::IMgr::Org(IMgrSession, $dn);

$name = $org->Name();$domain_name = $org-> PrimaryDomainName ();



$org->SetProperties(attr1, …);

$org->Create();$org->Delete();

@mailGroup_list = $org->GetMailGroups(cos_name1, …);

$org_unit = $org->OrgUnit($ou_name1, $ou_name2);$ou_list = $org->GetOrgUnits($flag = 0);

@ou_names = $org->GetOrgUnitNames($flag = 0);%ou_names = $org->GetOrgUnits($flag = 0);

my %attrs = %{ $org->Read('attr', …) };

$org->Add('attr' => val, ...);$org->SetAttributes('attr' => val, ...);$org->Remove('attr' => val, ...);

$org->AddAdmins($role, IMgrPerson ...);$org->RemoveAdmins($role, IMgrPerson ...);@adm_list = $org->GetAdmins($role ...);

Methods not called outside of InterManager API.

$org->IsSite();$org->IsCustomer();$dn = $org->MailGroupParentDN();$dn = $org-> MailTemplateParentDN ();

Methods

• new SwCom::IMgr::Org(IMgrSession, o_name, domain_name)Constructor for the IMgr::Org. The ‘domain_name’ argument is optional. If domain_name is absent it searches for the o_name in the DIT and gets the DN. Otherwise it constructs the DN from o_name and domain_name. The caller must pass both o_name and domain_name if he/she will be calling Create method next. Returns a reference to a SwCom::IMgr::Org object. Returns undef on error.

• new_from_dn SwCom::IMgr::Org(IMgrSession, $dn)Constructor for the IMgr::Org. Returns a reference to a SwCom::IMgr::Org object. Caller knows DN. Not to be used if Create will be called next!

• Name()Returns the organization’s name. This could also be read via $org->Read(’o’), but in general it is faster to access it via this method. Returns undef in case of error.

• MailTemplateParentDN()Returns the DN of the parent object under which default mail user template entries are located in an organization.

• PrimaryDomainName()Returns the primary domain name of the organization.



• SetProperties (attr => val, ...)Sets the properties to the corresponding values. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in. Valid properties are CreateNonExistentDomains. Set this property to 1 before calling Create. If the domains allowed for an organization (including the primary domain) should be created if they do not already exist. Set this property to 0 if the domains are expected to exist prior to calling Create. It always returns 1.

• Create(attr => val,…)Creates the customer organization and the associated LDAP entries. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. This routine will also set ACI rules governing the permissions various types of users have to read/write entries under the organization in the DIT. For example, all organization administrators will be able to create new organiza-tional units and users; ordinary users will not. Returns true on success, undef oth-erwise. See SwCom::IMgr::Entry::Create, SwCom::IMgr::Entry::Set Properties.

• Delete()Deletes the organization and the associated LDAP entries. The Person entries in the organization’s subtree must be deleted before calling this method. The caller must afterwards delete the primary domain name for the Org. Returns 1 on suc-cess, undef otherwise. (See SwCom::IMGR::Entry::Delete.)

• Read( ’attr’, ... )Reads the listed attributes on the current organization and returns a reference to hash of the attribute names mapped to arrays of values. If no attributes are passed in, it reads all attributes. Any attributes read that don’t yet have values on the LDAP entry are a valid key in the returned hash, mapped to the undef value. Returns undef on error. See SwCom::IMgr::Entry::Read.

• Add( ’attr’ => [val, ...], ... )Adds the specified attribute values to the organization entry. If exactly one argu-ment follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—values can not be added to the following attributes: objectclass, dc, o, businesscategory.

• Remove( ’attr’ => [val, ...], ... )Removes the specified attribute values from the organization entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—the Org’s primary domain name can not be removed from the ‘alloweddomains’ attribute. Also, a user can not remove values from the following attributes: objectclass, dc, o, businesscategory.

• SetAttributes( ’attr’ => [val, ...], ... )Replaces all values of the specified attributes on the organization entry. If exactly



one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not replace values on the following attributes: object-class, dc, o, businesscategory.

• GetMailGroups( cos_name1, … )Returns a list of the SwCom::IMgr::MailGroup objects for the organization. The mail groups are associated with a MailCOS. If one or more COS names are supplied, only return the mail groups associated with those Cos’s. In case of error it returns undef.

See also SwCom::IMgr::Entry

• AddAdmins( role, person1, ... );Grants an administrative role over this organization to the persons. Currently, parameter ‘role’ is not being used. The persons passed in are SwCom::IMgr::Person objects. All persons are added to the organizational administrator group. Returns 1 on success, undef otherwise.

• RemoveAdmins( role, person1, ... );Removes persons from the organization’s administrator group object, i.e. revokes an administrative role for persons over this organization. Currently ‘role’ is ignored. The persons passed in are SwCom::IMgr::Person objects. All persons are removed from the organizational administrator group. Returns 1 on success, undef otherwise.

• GetAdmins( role... )Returns a list of SwCom::IMgr::Person objects corresponding to the organiza-tion administrators. Currently ‘role’ is ignored. All persons returned are from the organizational administrator group. In case of error it returns undef.

• OrgUnit(ou_name)Returns a reference to an SwCom::IMgr::OrgUnit object, identified by its name, located beneath the current organization object in the LDAP hierarchy. In case of error it returns undef.

For example, $org->OrgUnit( “dev”) under the organization unit “eng”, under an organization object with DN dc=worldnet, dc=att, dc=com would return a SwCom::IMgr::OrgUnit object with the DN ou=dev,ou=eng,dc=world-net,dc=att,dc=com.

• GetOrgUnitNames(flag = 0);Returns names of the organizational units beneath the organization object. If flag is 1, return the names of the organizational units that are the first level children under the organization within the DIT.

If flag is 0, names of all the organizational units beneath the organization object are returned. Entries are returned as an array of comma delimited OU names, such that the hierarchical relationship of OU’s is preserved.

If flag is 0 (default) and assuming org units: a/m, a/n, a/n/x, a/b returns an array of arrays listing children organizational units.



ie: ( [a],[a, m], [a, n],[a, n, x],[a, b],)

In case of error it returns undef.

• GetOrgUnits( flag = 0 )Returns names of the organizational units beneath the organization object. If flag is 1, return the names of the organizational units that are the first level children under the organization within the DIT. If flag is 0, names of all the organizational units beneath the organization object are returned.

Entries are returned as a reference to a hash of hashes {{ou1 => {}}, ...} pre-serving the hierarchy. Every key/value is: <OU name>/<hash of children>. If an OU does not have children, the value is the empty hash {}. Note that if flag is 1, all child hash values are the empty hash {}.

For example, assuming org units: a/m, a/n, a/n/x, a/b the function returns a reference to a hash of hashes mapping org units to their children.

ie: { a => { m => {}, n => { x => {}, }, b => {},}

In case of error it returns undef.

• Search( Session, attr, value, op )Returns an array of organization names based on the search expression ‘attr’ ‘op’ ‘value’. ‘op’ maybe 'starts_with' (default), or 'is'. This routine may not be called through a $self pointer. It should be called using the fully qualified name of the function. In case of error it returns undef.

• IsSite()Returns 1 if the organization is a site (ISP), else 0. In case of error, it returns undef. This method is not called outside of InterManager API.

• IsCustomer()Return 1 if the organization is an ISP customer organization, else 0. In case of error, it returns undef. This method is not called outside of InterManager API.

• MailGroupParentDN()Returns the DN of the parent object under which the mail group entries are located in an organization. This method is not called outside of InterManager API.

SwCom::IMgr::OrgUnitDescription

LDAP Organization Units. An LDAP entry that represents an organizational unit beneath an organization. The SwCom::IMgr::OrgUnit helps to organize and identify organizational unit entries in the LDAP hierarchy.



Synopsis

$org_unit = new SwCom::IMgr::OrgUnit(IMgrSession, $org, $ou_name, ...);$org_unit = new_from_org SwCom::IMgr::OrgUnit(IMgrOrg, $ou_name, ...);$org_unit = new_from_ou SwCom::IMgr::OrgUnit(IMgrOrgUnit, $ou_name, ...);$org_unit = new_from_dn SwCom::IMgr::OrgUnit($dn);

$name = $org_unit->Name();$org_name = $org_unit->OrgName();

$org_unit->Create(attr => [val]. …);$org_unit->Delete();

my %attrs = %{ $org_unit->Read('attr', …) };

$org_unit->AddAdmins($role, IMgrPerson ...);$org_unit->RemoveAdmins($role, IMgrPerson ...);@adm_list = $org_unit->GetAdmins($role...);

Methods not called outside of InterManager API.

$org_unit->IsConsumerOrgUnit();$org_unit->IsBusinessOrgUnit();

Methods

• ConstructorsConstructors for the SwCom::IMgr::OrgUnit. Return a reference to a SwCom::IMgr::OrgUnit object.

$org_unit = new SwCom::IMgr::OrgUnit(IMgrSession, org_name, ou_name, ...);

This form requires a SwCom::IMgr::Session, the org name and at least one ou_name.

$org_unit = new_from_org SwCom::IMgr::OrgUnit(IMgrOrg, $ou_name, ...);

The second form, requires a valid instance of SwCom::IMgr::Org object and at least one ou_name.

$org_unit = new_from_ou SwCom::IMgr::OrgUnit(IMgrOrgUnit, $ou_name, ...);

The third form, requires a valid instance of SwCom::IMgr::OrgUnit object and at least one ou_name.



$org_unit = new_from_dn (IMgrSession, $dn)

The fourth form, requires a SwCom::IMgr::Session and the full DN of an organi-zation unit.In the first three forms, more than 1 OU name may be specified to get nested OrgUnits. OU names should be listed in descending hierarchical order. The first OU name must be immediately beneath the organization for the first and second forms, and the organizational unit in the third form. The last OU name is the orga-nizational unit to be instantiated. Also see SwCom::IMgr::Org, SwCom::IMgr::Entry

• Name()Returns the organizational unit name. This is faster than reading from the ‘ou’ attribute from the entry. In case of error it returns undef.

• OrgName()Returns the organizational unit’s parent organization name. Faster than reading from the ‘o’ attribute from the entry. In case of error it returns undef.

• Create( attr1 => [attr_val1], … )Creates an organizational unit object. . If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. This routine will also set ACI rules governing the permissions various types of users have to read/write entries under the organizational unit in the DIT. (e.g. all organizational unit administrators will be able to create new organizational units and users beneath the current OU; ordinary users will not.) Returns 1 on success, undef oth-erwise.

The caller must pass in ’businesscategory’ => ’consumer’ if they want to create a consumer OU under a provider subtree.

Restrictions—a user can not pass in the following attributes: objectclass, ou. One can not create a consumer OU underneath a customer organization subtree.

• Delete()Deletes the OU entry and the associated entries pertaining to an email based Orga-nizational Unit in the DIT. ACI rules referring to these entries are deleted too. This method assumes that all children entries of type SwCom::IMgr::Person have already been deleted. Returns 1 on success, undef otherwise.

• Read( ’attr’, ... )Reads the listed attributes on the current Organization Unit and returns a reference to hash of the attribute names mapped to arrays of values. If no attributes are passed in, reads all attributes. Any attributes that are read that do not yet have val-ues on the LDAP entry are a valid key in the returned hash, mapped to the undef value. Returns undef on error. See SwCom::IMgr::Entry::Read.

• AddAdmins( role, IMgrPerson, ... )Grants an administrative role over this OU to persons. Currently ‘role’ is not being used. Creates the OU admin group if it does not already exist. All persons are added to the organizational unit administrator group. The persons passed in are SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.

• RemoveAdmins( role, ImgrPerson, ... )



Removes persons from the OU administrators’ group object, i.e. revokes an administrative role for persons over this OU. Currently ‘role’ is ignored. All per-sons are removed from the Organizational Unit administrative group. The persons passed in are SwCom::IMgr::Person objects. Returns 1 on success, undef other-wise.

• GetAdmins( role, ... )Returns a list of SwCom::IMgr::Person objects corresponding to the OU adminis-trators. Currently ‘role’ is ignored. In case of error it returns undef.

• IsConsumerOrgUnit()Return 1 if this OU contains consumer accounts, else 0. A consumer account is for an email user not affiliated with a customer organization. This method is not called outside of InterManager API.

• IsBusinessOrgUnit()Return 1 if this OU contains business accounts, else 0. All OUs within customer organizations are business OUs. OUs within an provider’s organization may be business or consumer OUs with the restriction that business OUs may not reside under a consumer OU. This method is not called outside of the InterManager API.

SwCom::IMgr::PersonDescription

An LDAP entry that represents a person associated with an organization or an organizational unit. If an e-mail account is associated with the end-user, the attributes of that account can also be accessed directly through the Person object.

Synopsis

$person = new_from_parent SwCom::IMgr::Person($parent, $person_name, $cos_name);

$person = new_from_mailgroup SwCom::IMgr::Person($parent, $person_name, IMgrMailGroup);

$person = new_from_name SwCom::IMgr::Person (IMgrSession, $person_name, $parent, $immchild=0);

$person = new_from_dn(IMgrSession, $dn);

$name = $person->Name();

$smtp = $person->Smtp();

$person ->SetProperties(’attr’ => val, ...);

$person ->Create(’attr’ => val, ...);$person ->Delete();

my %attrs = %{ $person->Read('attr', …) };

$mg = $person->GetMailGroup();



$mt = $person->GetMailTemplate();

$org->Add(’attr’ => val, ...);$org->SetAttributes(’attr’ => val, ...);$org->Remove(’attr’ => val, ...);

$person ->Move($org, $ou_name ...);

Note: When the plainPassword parameter is specified in any SwCom::IMgr::Person operations and the hash function is set to something other than clear, the input password is encrypted in the client before it is sent to the Directory.

Methods

• new_from_parent SwCom::IMgr::Person ( parent, name, cos_name)Constructor for the SwCom::IMgr::Person. Returns a reference to a SwCom::IMgr::Person object.

where:

• new_from_mailgroup SwCom::IMgr::Person ( parent, name, IMgrMail-Group)Constructor for the IMgrPerson. Returns a reference to a SwCom::IMgr::Per-son object.

where:

• new_from_name SwCom::IMgr::Person( IMgrSession, name, parent, immchild=0 )Constructor for the SwCom::IMgr::Person. Returns a reference to a SwCom::IMgr::Person object.

parent The LDAP entry structurally above the Person in the DIT (may be of type SwCom::IMgr::Org or SwCom::IMgr::OrgUnit).

name The UID value (smtp address) for the Person.

cos_name The COS to be associated with the mail account for the person.



IMgrMailGroup A reference to a SwCom::IMgr::MailGroup object, representing the mail group of which the Person is to be made a member. This links the Person to their mail COS. (The mail COS establishes the various services supported for the Person’s mailbox.)



where:

Note: If immchild is 1, the Person is directly underneath the parent. Otherwise, we must search for the Person. If ‘parent’ is supplied, search under the parent, otherwise search from the DIT root.

• new_from_dn SwCom::IMgr::Person( IMgrSession, dn )Constructor for the SwCom::IMgr::Person. Returns a reference to a SwCom::IMgr::Person object. Construct a Person object given the full Distin-guished Name.

• Name()Returns the ‘uid’ attribute value (happens to be the SMTP Address) for the person. In case of error it returns undef.

• Smtp()Returns the SMTP Address (‘mail’ attribute value) for the person. In case of error it returns undef.

• GetMailGroup()Returns the mail group object (SwCom::IMgr::MailGroup) for this person. In case of error it returns undef.

• GetMailTemplate()Returns the mail template object (SwCom::IMgr::MailTemplate) for this per-son. In case of error it returns undef.

• SetProperties( ’attr’ => val, ... )Sets the properties to the specified values. If exactly one argument follows self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in.

Valid properties are AccountExists, LdapEntryExists each of which take values 1 or 0; OnAccountExistence, OnLdapExistence each which take val-ues fail_if_exists or ‘ok_if_exists’. These four properties are used to control the behavior of Create(). (See SwCom::IMgr::Person::Create()).

If AccountExists is set to 1, Create() will verify that the account record for the Person exists. Otherwise, Create() will attempt to create the account record. If LdapEntryExists is set to 1, Create() will verify that the LDAP entry for the Person exists in the DIT. Otherwise, Create() will attempt to create the LDAP entry.

OnAccountExistence determines what happens if Create() attempts to create the account record for the Person and it already exists. If OnAccountExistence

IMgrSession





is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.

Likewise, OnLdapExistence determines what happens if Create() attempts to create the LDAP entry for the Person and it already exists. If OnLdapExistence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists. Always returns 1.

• Create( attr1 => [attr_val1], … )Creates a Person’s object in the directory. The Person’s parent entry must already exist in the directory. One of the following constructors must have been used to construct the Person object: new_from_parent or new_from_mailgroup. Depending on the property settings, the Person’s LDAP entry and/or account record may be read to verify it already exists. (See SetProperties()).Returns 1 on success, undef otherwise.

Restrictions—a user can not pass in the following attributes: objectclass, mail, uid, mailgroup, allowedservices; and the Mail API attributes: smt-pAddress, cosName, resultCos.

• Delete()Deletes the Person object from the directory. The Person is removed from the mail group and any administrative groups of which they are a member. Returns 1 on success, undef otherwise.

• Move( org, ou_name ... )Moves the person from their current location in the DIT to the Organizational Unit underneath the Organization specified by org. If ou_name is not passed in, the Person is moved directly under the Organization. The org argument may be a ref-erence to a SwCom::IMgr::Org object or the Organization’s name. All OU names supplied may only be names (as opposed to object references). Returns 1 on success, undef otherwise.

• Read( ’attr’, ... )Reads the listed attributes on the current Person object and returns a reference to hash of the attribute names mapped to arrays of values. If no attributes are passed in, it reads all attributes. Any attributes read that do not yet have values on the LDAP entry are a valid key in the returned hash, mapped to the undef value. Returns undef on error. See also SwCom::IMgr::Entry::Read.

• Add( ’attr’ => [val, ...], ... )Adds the specified attribute values to the Person entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not add values to the following attributes: objectclass, uid, mail, mailgroup, allowedservices, preferredservices; and the InterMail API attributes: smtpAddress, popAddress, mssHost, emailIntID, password, hash, status, acCos, resultCos.

Use SetAttributes() instead.

• Remove( ’attr’ => [val, ...], ... )Removes the specified attribute values from the Person entry. If exactly one argu-



ment follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Use SetAttributes() instead. Returns 1 on success, undef oth-erwise.

Restrictions—a user can not remove values from the following attributes: objectclass, uid, mail, mailgroup, allowedservices, preferredser-vices; and the InterMail API attributes: smtpAddress, popAddress, mssHost, emailIntID, password, hash, status, acCos, resultCos.

• SetAttributes( ’attr’ => [val, ...], ... )Replaces all values of the specified attributes on the Person entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not replace values on the following attributes: object-class, uid, allowedservices.

• Roles()NOT YET IMPLEMENTED.

• GetAdminAuthority()Returns a hash mapping an administrative role to those entries upon which the per-son has that authority. Valid authoritative roles for the hash keys are ‘site admin’, ‘csr admin’, ‘org admin’, and ‘ou admin’. The site, csr, and org admin roles map to arrays of entry names. Example: ( ‘org admin’ => [‘Widget Services’, ‘ABC Printing, Inc.’]). The ou admin role maps to an array of arrays as follows: (‘ou admin’ => [[‘Widget Services’, ‘Engineering’, ‘Sustaining’], [‘Widget Services’, ‘Marketing’, ‘Foreign’]], ). Here, each sub-array contains the organization and organizational unit names as its elements. Element zero contains the organization name, consecutive elements contain the child organizational units, with the final organizational unit stored as the last element.

• GetOrgUnitNames()Return the Organizational Unit names structurally above the Person in as a list. Within the list, the OU’s are in descending, hierarchical order. For example, if the Person’s DN is:

[email protected],ou=dev,ou=west,ou=eng,dc=accordance,dc=com

the list returned is: eng, west, dev

• Search( IMgrSession, @attrs, @ops, $value, $boolop= ’AND’ )Returns a list of ‘uids’ for the Persons which match the search criteria. The array of attributes is related to the value by the parallel items in the ‘ops’ (operations) array. This relationship may be 'is' or 'starts_with'. So for instance, the triplet: <$attr[0] $ops[0] $value> forms one filter expression. ‘boolop’ may be 'AND' or 'OR'. ‘boolop’ is used to connect individual filters to construct a complex filter. The default for ‘boolop’ is 'AND'. In case of error it returns undef. See also SwCom::IMgr::Entry.



SwCom::IMgr::MailGroupDescription

LDAP Mail Group. This object coordinates the process of the email administration for a group of people. The mail group’s primary purpose is to relate a set of mailboxes (owned by Persons) to a unique mail COS and to potentially restrict how many of mailboxes with this COS may be created. The mail COS determines the services actually supported upon a mailbox.

Attributes include a pointer to a mail COS object (see below), a pointer to a mail template object (optional), a quota for the maximum number of people that can be assigned to this group (and hence use this mail COS) etc. See also SwCom::IMgr::Entry.

Synopsis

$mg = new SwCom::IMgr::MailGroup(IMgrOrg, $site_name, $cos_name);$mg = new_from_org SwCom::IMgr::MailGroup(IMgrOrg, $cos_name);$mg = new_from_cos SwCom::IMgr::MailGroup(IMgrOrg, IMgr-MailCOS);$mg = new_from_dn SwCom::IMgr::MailGroup(IMgrSession, $dn);

$name = $mg->Name();

$mg ->SetProperties(’attr’ => val, ...);

$mg ->Create(’attr’ => val, ...);$mg ->Delete();

my %attrs = %{ $mg->Read('attr', …) };

$mt = $mg->GetMailTemplate();$cos = $mg->GetMailCOS();

$mg->Add('attr' => val, ...);$mg->SetAttributes('attr' => val, ...);$mg->Remove('attr' => val, ...);

Methods

• new SwCom::IMgr::MailGroup( IMgrOrg, prov_name, cos_name )Constructor for the SwCom::IMgr::MailGroup. Returns a reference to a SwCom::IMgr::MailGroup object.

Caller passes the SwCom::IMgr::Org object for the organization owning the mail group, the provider owning the COS, and the COS name associated with the mail group. The caller may use this constructor if they will be calling Create next.

In case of error, it returns undef.

• new_from_org SwCom::IMgr::MailGroup(IMgrOrg, $cos_name)Constructor for the SwCom::IMgr::MailGroup. Returns a reference to a



SwCom::IMgr::MailGroup object.

Caller passes the SwCom::IMgr::Org object for the organization owning the mail group, and the COS name associated with the mail group. This constructor calculates the DN directly from the IMgrOrg’s DN.

Restrictions—this is not to be used if Create() will be called next

• new_from_COS SwCom::IMgr::MailGroup(IMgrOrg, IMgrMailCos)Constructor for the SwCom::IMgr::MailGroup. Returns a reference to a SwCom::IMgr::MailGroup object.

Caller passes the SwCom::IMgr::Org object for the organization owning the mail group, and the SwCom::IMgr::MailCos object associated with the mail group. The caller may use this constructor if they will be calling Create() next. In case of error, it returns undef.

• new_from_dn SwCom::IMGR::MailGroup( IMgrSession, $dn )Constructor for the IMgr::MailGroup. Returns a reference to a SwCom::IMgr::MailGroup object. Caller knows the DN. In case of error, it returns undef.

Restrictions—this is not to be used if Create() will be called next!

• Name()Returns the mail group’s name. . In case of error returns an undef.

• GetMailCOS()Returns a reference to a SwCom::IMgr::MailCOS object associated with this mail group. In case of error it returns undef.

• GetMailTemplate()Returns SwCom::IMgr::MailTemplate object associated with this mail group. In case of error it returns undef.

• GetMailTemplateDN()Reads the mail template DN from the mail group object.

• SetProperties( ’attr’ => val, ... )Sets the properties to the specified values. If exactly one argument follows self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in. Always returns 1.

Valid properties are LdapEntryExists, which takes values 1 or 0, and OnLdapExistence, which takes values fail_if_exists or ok_if_exists. These properties are used to control the behavior of Create(). (See SwCom::IMgr::MailGroup::Create()).

If LdapEntryExists is set to 1, Create() will verify that the LDAP entry for the mail group exists in the DIT. Otherwise, Create() will attempt to create the LDAP entry.

OnLdapExistence determines what happens if Create() attempts to create the LDAP entry for the MailGroup and it already exists. If OnLdapExistence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.



• Create (’attr’ => [value ...], ...)Creates a mail group entry in the directory. If exactly one argument follows self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in.

The caller must construct the SwCom::IMgr::MailGroup object before calling this method using the following constructors: new(), new_from_COS().

Caller may pass in the max users that may own a mailbox using the associated COS. For example ’maxusers’ => [number]. Otherwise, the max users defaults to 0 (infinity). Returns 1 on success, undef otherwise.

Restrictions—a user can not pass in the following attributes: objectclass, cn, numusers.

• Delete()Deletes a mail group entry from the directory. Fails if there are any members. Returns 1 in case of success and undef otherwise.

• Read( ’attr’, ... )Reads the listed attributes on the current mail group object and returns a reference to hash of the attribute names mapped to arrays of values. If no attributes are passed in, it reads all attributes. Any attributes that are read that do not yet have values on the LDAP entry are a valid key in the returned hash, mapped to the undef value. Returns undef on error. See also SwCom::IMgr::Entry::Read.

• Add( ’attr’ => [val, ...], ... )Adds the specified attribute values to the mail group entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not add values to the following attributes: objectclass, cn, numusers, maxusers.

• Remove( ’attr’ => [val, ...], ... )Removes the specified attribute values from the mail group entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not remove values from the following attributes: objectclass, cn, numusers, maxusers.

• SetAttributes( ’attr’ => [val, ...], ... )Replaces all values of the specified attributes on the Person entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not replace values on the following attributes: object-class, cn, numusers.

• AddMembers (person1, ...)Adds one or more members to a mail group. Checks to make sure that the current member count is not exceeding the max allowed. Max may be 0, which is infinity.



Specified persons are the SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.

• RemoveMembers (person1, ...)Removes one or more members from a mail group. Specified persons are the SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.

SwCom::IMgr::MailTemplate Description

LDAP Mail Template. A mail template is used to establish any initial attribute value(s) for a newly created Person object. A mail template is referred to by a mail group and is associated with the mail COS also referred by the same mail group.

Upon creating the Person, all attribute values from the relevant mail template are read and placed upon the Person object. These attributes may not be passed into the Create() method for the Person. Some of these attributes may, however, be modified after the Person is created. See the SetAttributes(), Add(), and Remove() methods for more information.

Synopsis

$mt = new_from_org SwCom::IMgr::MailTemplate(IMgrOrg, $cos_name);$mt = new_from_dn SwCom::IMgr::MailTemplate(IMgrSession, $dn);

$name = $mt->Name();$cos = $mt->GetMailCOS();$mg = $mt->GetMailGroup();

$mt ->SetProperties(’attr’ => val, ...);

$mt ->Create(’attr’ => val, ...);$mt ->Delete();

my %attrs = %{ $mt->Read('attr', …) };

$mt->Add('attr' => val, ...);$mt->SetAttributes('attr' => val, ...);$mt->Remove('attr' => val, ...);

Methods

• new_from_org SwCom::IMgr::MailTemplate( IMgrOrg, cos_name )Constructor for the SwCom::IMgr::MailTemplate object. Returns a reference to a SwCom::IMgr::MailTemplate object.

Caller passes the IMgrOrg object for the organization owning the mail template and the COS name associated with the template. Returns undef in case of an error.

• new_from_dn SwCom::IMgr::MailTemplate( IMgrSession, dn )Constructor for the SwCom::IMgr::MailTemplate object. Returns a reference to a SwCom::IMgr::MailTemplate object. Caller knows the DN. Returns undef in case



of an error.

Restrictions—this is not to be used if Create() will be called next.

• Name()Returns mail template’s name.

• GetMailCOS()Returns the SwCom::IMgr::MailCOS object associated with the mail group ref-erencing this template. Returns undef in case of an error.

• GetMailGroup()Returns the SwCom::IMgr::MailGroup object associated with the mail group referencing this template. Returns undef in case of an error.


Valid properties are LdapEntryExists, which takes values 1 or 0, and OnLdapExistence, which takes values ‘fail_if_exists’ or ‘ok_if_exists’. These properties are used to control the behavior of Create(). See also SwCom::IMgr::MailTemplate::Create().

If LdapEntryExists is set to 1, Create() will verify that the LDAP entry for the mail group exists in the DIT. Otherwise, Create() will attempt to create the LDAP entry.

OnLdapExistence determines what happens if Create() attempts to create the LDAP entry for the MailGroup and it already exists. If OnLdapExistence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.

Always returns 1.

• Create (’attr’ => [value ...], ...)Creates a mail template entry in the directory. If exactly one argument follows self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in.

The caller must construct the SwCom::IMgr::MailTemplate object before call-ing this method using the new_from_org() constructor.

Restrictions—a user can not pass in the following attributes: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.

Returns 1 on success, undef otherwise.

• Delete ()Deletes a mail template entry from the directory. Fails if there are mail group entries referencing the mail template entry. Returns undef in case of error.

• Read( ’attr’, ... )Reads the listed attributes on the current mail template object and returns a refer-ence to hash of the attribute names mapped to arrays of values. If no attributes are passed in, reads all attributes. Any attributes that are read that do not yet have val-ues on the LDAP entry are a valid key in the returned hash, mapped to the undef



value. Returns undef on error. See also SwCom::IMgr::Entry::Read.

• Add( ’attr’ => [val, ...], ... )Adds the specified attribute values to the mail template entry. If exactly one argu-ment follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not add values to the following attributes: objectclass, mup, mail, mailid; and the InterMail API attributes: smtpAddress, emailIn-tID.

• Remove( ’attr’ => [val, ...], ... )Removes the specified attribute values from the mail template entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not remove values from the following attributes: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.

• SetAttributes( ’attr’ => [val, ...], ... )Replaces all values of the specified attributes on the mail template entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise.

Restrictions—a user can not replace values on the following attributes: object-class, mup, mail, mailid; and the Mail API attributes: smtpAddress, email-IntID.

SwCom::IMgr::MailCOSDescription

Mail class of service. It corresponds to an LDAP entry whose attributes: preferredservices and allowedservices (hashes of service/value settings) together control the availability of features to a group of end-users. Also referred to as a MailUserPolicy. See also SwCom::IMgr::Entry.

Synopsis

$cos = new SwCom::IMgr::MailCOS( IMgrSession, $prov_name, $cos_name );$cos = new_from_provider SwCom::IMgr::MailCOS( IMgrPro-vider, $cos_name );$cos = new_from_dn SwCom::IMgr::MailCOS( IMgrSession, $dn );

$name = $cos->Name();

$cos ->SetProperties(’attr’ => val, ...);

$cos ->Create(’attr’ => val, ...);



$cos ->Delete();

my %attrs = %{ $mt->Read('attr', …) };

$cos ->Add('attr' => val, ...);$cos ->SetAttributes('attr' => val, ...);$cos ->Remove('attr' => val, ...);

Methods

• new (IMgrSession, prov_name, cos_name)Constructor for the SwCom::IMgr::MailCOS object. Returns a reference to a SwCom::IMgr::MailCOS object. Caller passes name of provider owning the COS and the COS name. Returns undef in case of error.

• new_from_provider (IMgrProvider, $cos_name)Constructor for the SwCom::IMgr::MailCOS. Returns a reference to a SwCom::IMgr::MailCOS object. Caller passes in the IMgrProvider object for the provider owning the COS and the COS name. Returns undef in case of error.

• new_from_dn (Session, $dn)Constructor for the SwCom::IMgr::MailCOS object. Returns a reference to a SwCom::IMgr::MailCOS object. Caller knows the DN. In case of error it returns undef.

Restrictions—this is not to be used if Create() will be called next.

• Name()Returns COS name.


Valid properties are MailCOSExists, LdapEntryExists each which take val-ues 1 or 0; OnMailCOSExistence, OnLdapExistence each which take values fail_if_exists or ok_if_exists. These four properties are used to control the behavior of Create(). (See SwCom::IMgr::MailCOS::Create()).

If MailCOSExists is set to 1, Create() will verify that the account record for the Person exists. Otherwise, Create() will attempt to create the account record. If LdapEntryExists is set to 1, Create() will verify that the LDAP entry for the Person exists in the DIT. Otherwise, Create() will attempt to create the LDAP entry.

OnMailCOSExistence determines what happens if Create() attempts to create the name in the COS table for the mail COS and it already exists. If OnMailCO-SExistence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.

Likewise, OnLdapExistence determines what happens if Create() attempts to create the LDAP entry for the mail COS and it already exists. If OnLdapEx-istence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.



Always returns 1.

• Create (’attr’ => [value ...], ...)Creates a mail COS entry in the directory and a new COS name in the COS name table. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of property name/value pairs. Otherwise, it assumes that prop-erty name/value pairs were passed in.

The caller must construct the SwCom::IMgr::MailCOS object before calling this method using one of the following constructors: new() or new_from_provider().


• Delete ()Deletes the mail COS entry from the directory provided no mail group entries are currently referring to it. This includes the LDAP entry, as well as, removing COS name from the COS name table.

Returns 1 in case of success undef otherwise.

• Read( ’attr’, ... )Reads the listed attributes on the current mail COS object and returns a reference to hash of the attribute names mapped to arrays of values. If no attributes are passed in, it reads all attributes. Any attributes that are read that do not yet have values on the LDAP entry are a valid key in the returned hash, mapped to the undef value.

The attr parameter @attrs, lists the attributes the caller wishes to receive back. These are returned in a hash of attr name/[attr values] pairs. (The values are set in an array because LDAP allows multiple values for an attribute.) If @attrs is empty or undefined, all attributes of the MailCOS object are returned.

Returns undef on error.

• Add( ’attr’ => [val, ...], ... )Adds the specified attribute values to the mail COS entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in.

Restrictions—a user can not add values to the following attributes: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.


Note: Class of service attributes cannot be modified using Add. Use SetAt-tributes to change values of class of service attributes.

• Remove( ’attr’ => [val, ...], ... )Removes the specified attribute values from the mail COS entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in.



Restrictions—a user can not remove values from the following attributes: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.


• SetAttributes( ’attr’ => [val, ...], ... )Replaces all values of the specified attributes on the mail COS entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in.

Restrictions—a user can not replace values on the following attributes: object-class, mup, mail, mailid; and the Mail API attributes: smtpAddress, email-IntID.


SwCom::IMgr::ProviderDescription

The following is the set of LDAP entries in DIT that represent an Internet Service Provider. Sub-entries created for an ISP include: mail COS entries, and Site, CSR, Org administrative groups. The mail template, mail group and OU administrative group entries are included if the ISP is to reside as an InterManager Organization in the DIT. (i.e., they outsource email services to themselves.)

Synopsis

$site = new SwCom::IMgr::Provider(IMgrSession, $site_name, $domain_name);

$site_list = SwCom::IMgr::Provider::List(IMgrSession);

$name = $site->Name();$domain = $site->PrimaryDomainName();

$site->Create();$site->Delete();

$org = $site->GetOrg($org_name = $site_name);

$site->AddAdmins($role, IMgrPerson ...);$site->RemoveAdmins($role, IMgrPerson ...);@adm_list = $site->GetAdmins($role...);

@group_list = $site->GetMailGroups($org_name);@cos_list = $site->GetMailCOSs();

Methods not called outside of the InterManager API.

$site->IsSite(); $site->IsCustomer();$dn = $site->MailCOSParentDN();



$dn = $site->MailGroupParentDN(); $dn = $site->MailTemplateParentDN();$site->CreateOrgUnit();

Methods

• new SwCom::IMgr::Provider( IMgrSession, prov_name, domain_name )Constructor for the SwCom::IMgr::Provider. The SwCom::IMgr::Provider object represents an ISP in the DIT. The domain_name argument is optional. If domain_name is absent it searches for the prov_name in the DIT and gets the DN. Otherwise it constructs the DN from prov_name and domain_name.

The caller must pass both prov_name and domain_name if he/she will be calling the Create() method next.

Returns a reference to a SwCom::IMgr::Provider object.

• List( IMgrSession )Returns a reference to an array of the names of all ISPs in the DIT. The ISP Orga-nization entry is distinguished by its businesscategory attribute, which con-tains the value provider. It must not be called with $self as the first arguments; call using the fully qualified names. Return undef in case of an error.

Note: Currently, the InterManager only supports one ISP in the DIT.

• Name()Returns Provider’s name (e.g. Widget Services).

• PrimaryDomainName()Return Provider’s primary domain name (e.g. widget.abc.com).

• Create('attr' => [value ...], …)Creates the new provider Organization entry and all other relevant entries pertain-ing to an ISP in the DIT. If exactly one argument follows self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in.


• Delete();Deletes the provider entry and other relevant entries pertaining to an ISP operation from the DIT. OUs, Persons, MailGroups, and MailTemplates must already have been removed.

Returns true on success, undef otherwise.

• GetOrg( org_name )Returns a reference to an SwCom::IMgr::Org object specified by org_name. It is required that this organization be a customer of the provider, or be the provider itself. If org_name is undefined, returns a SwCom::IMgr::Org for the site’s organization otherwise returns the SwCom::IMgr::Org for the specified organi-zation.

• AddAdmins( role, ImgrPerson, ... );Grants an administrative role over this Provider to Persons. Role is ’site admin’,



'csr admin', or ‘org admin’. The people passed in are SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.

• RemoveAdmins( $role, ImgrPerson, ... );Removes the specified people from the appropriate administrative group within the Provider - i.e. revokes an administrative role for the Persons. Role is ’site admin' , 'csr admin', or ‘org admin’. The people passed in are SwCom::IMgr::Person objects.


• GetAdmins( role, ... );Returns the SwCom::IMgr::Person objects for the Persons with the specified administrative role(s) for the Provider. If roles aren't specified, the default is ‘site admin.’

Returns undef in case of an error.

• GetMailGroups( org_name );Returns a list of SwCom::IMgr::MailGroup objects corresponding to the mail groups defined for the specified Organization. If org_name is not specified, the default is the Provider’s organizational name.


• GetMailCOSs()Returns a list of SwCom::IMgr::MailCOS objects corresponding to all the mail COS objects owned by the Provider. These include the private COS’s used by the ISP for its own internal mail users (ie. employees). These also include the COS’s used for consumer accounts. (Consumer accounts are stored under the Provider’s Organization subtree within the DIT.)


• GetMailCOSNames()Returns a list of COS names corresponding to all the mail COS objects owned by the Provider. These include the private COS’s used by the ISP for its own mail users (ie. employees). These also include the COS’s used for consumer accounts. (Consumer accounts are stored under the Provider’s Organization subtree within the DIT.)

Returns reference to an array or undef in the of an error.

• IsSite()Returns 1.

• IsCustomer()Returns 0.

• MailGroupParentDN()Returns the DN of the entry (mail data DN) beneath which the mail group entries are stored in the Provider’s subtree.

• MailTemplateParentDN()Returns the DN of the entry (mail data DN) beneath which the mail template entries are stored in the Provider’s subtree.

• MailCOSParentDN()



Returns the DN of the entry (mail policies DN) beneath which the mail COS entries are stored in the Provider’s subtree.

• CreateOrgUnit(ou, attrs)Creates an Org Unit within the Provider’s subtree in the DIT. The ou argument is an SwCom::IMgr::OrgUnit object. The attrs argument is a reference to hash of attribute name-value pairs. The ou could be of business or consumer type. If undef, it is assumed to be a business out. Returns 1 on success, undef otherwise.

SwCom::IMgr::AdminGroup Description

The InterManager object that represents an administrative group of people. Note that this object is used internally when adding or removing administrators to/from Organizations, Organizational Units, and Providers.

Synopsis

$admin_group = new SwCom::IMgr::AdminGroup($parent, $name);

$admin_group = new_from_dn SwCom::IMgr::Admin-Group(IMgrSession, $dn);

$admin_group->Create();$admin_group->Delete();

$admin_group->AddAdmins(IMGRPerson ...);$admin_group->RemoveAdmins(IMGRPerson ...);@adm_list = $admin_group->GetAdmins();

Methods

• new SwCom::IMgr::AdminGroup(parent, name)Constructor for the SwCom::IMgr::AdminGroup. Returns a reference to a SwCom::IMgr::AdminGroup. The ‘parent’ argument is an SwCom::IMgr::Entry object.

• Create('attr' => [value ...],…)Creates an admin group. If exactly one argument follows self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in.

The caller is expected to fill in the ’description’ describing what kind of admin group they are making: site admins’, ‘csr admins’, ‘org admins’, ‘ou admins’. Caller has previously established the name of the group via the constructor. Returns true on success, undef otherwise.

Note: The ‘member’ attribute requires DNs. Caller is expected to have resolved their members to DNs (perhaps by $person->GetDN()).

• Delete()Deletes the admin group. Benign if admin group doesn’t exist. Returns true on suc-



cess, undef otherwise.

• AddAdmins( person1, ... )Adds the specified Persons to the admin group. The people passed in are SwCom::IMgr::Person objects. The admin group entry must already exist in the directory. Returns 1 on success, undef otherwise.

• RemoveAdmins( person1, ... )Removes the specified Persons from the admin group. The people passed in are SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.

• GetAdmins()Returns SwCom::IMgr::Person objects corresponding to the members belong-ing to the admin group. Returns undef in case of an error.

SwCom::IMgr::DomainDescription

This represents a domain. This class inherits most of its functionality from SwCom::Mail::Domain. See also SwCom::Mail::Domain.

Synopsis

$domain = new SwCom::IMGR::Domain(IMGRSession, %attrs);

$name = $domain->Name();

$domain ->SetProperties(’attr’ => val, ...);

$domain->Create(’attr’ => val, ...);$domain->Delete();

my %attrs = %{ $domain->Read('attr', …) };

$domain->SetAttributes('attr' => val, ...);

Methods

• new SwCom::IMgr::Domain(IMgrSession, %attrs);Constructor for the SwCom::IMgr::AdminGroup. Returns a reference to a SwCom::IMgr::Domain object that has the specified attribute settings.

• List( IMgrSession );Lists all domains that have been created. A domain may be added to any or all Organizations. $self must not be passed in; only call this method using its fully qualified name.

• Name()Returns the domain name.




Valid properties are MailDomainExists, which takes values 1 or 0; OnMailDo-mainExistence, which take values fail_if_exists or ok_if_exists. These properties are used to control the behavior of Create(). (See SwCom::IMgr:: Domain::Create()).

If MailDomainExists is set to 1, Create() will verify that a domain record for the domain exists. Otherwise, Create() will attempt to create the domain record.

OnMailDomainExistence determines what happens if Create() attempts to create the name in the domain record and it already exists. If OnMailDomainEx-istence is set to fail_if_exists, an error is returned (undef), otherwise if set to ok_if_exists.

Always returns 1.

• Create( ’attr’ => [value ...], ...))Creates the domain. If exactly one argument follows self, it assumes that the argu-ment is a reference to a hash of property name/value pairs. Otherwise, it assumes that property name/value pairs were passed in. All attributes are passed through to SwCom::Mail::Domain::Create(). Depending on the property settings, the domain record may be read to verify it already exists. (See SetProperties()).

• Delete()It deletes the domain from the Mail domain table. If any Organization lists the domain as an allowed domain, do not delete the domain and return an error. Returns 1 on success, undef otherwise.

Note: This is the alloweddomains attribute of SwCom::IMgr::Org.

• SetAttributes( ’attr’ => [val], ...)Replaces all values of the specified attributes on the mail COS entry. If exactly one argument follows $self, it assumes that the argument is a reference to a hash of attribute name/value pairs. Otherwise, it assumes that attribute name/value pairs were passed in. Returns 1 on success, undef otherwise

Restrictions—all attributes are single valued only.

• Read()Reads all attributes on the current Domain object and returns a reference to hash of the attribute names mapped to arrays of values. Any attributes that are read that do not yet have a value in the domain record are a valid key in the returned hash, mapped to an empty array: []. Returns undef on error.


8LDAP Perl API

The LDAP (Lightweight Directory Access Protocol) Perl API provides a relatively easy way to contact an LDAP server. This API is a subset of the formal LDAP v2 API (see RFC 1823), along with extra functions added by Software.com to enable you to build provisioning scripts, billing reports, and so on.

This chapter describes the following functions of the LDAP Perl API:

• Error-processing function:

ldap_err2string

• Connection management functions:

ldap_openldap_simple_bind_sldap_unbind

• Functions that perform operations on entries:

ldap_add_sldap_modify_sldap_delete_sldap_modrdn_sldap_rename_sldap_search_sldap_count_entriesldap_get_all_entries

• Access Control Information function:

ldap_apply_aci_rule_s

• Memory management function:

ldap_msgfree



Error-Processing Function

ldap_err2string(rc)Returns:

An error string associated with the input parameter.

Parameters:

rc: Any return code from an LDAP API function call.

Description:

Returns an error string associated with an LDAP error code.

Example:

my $rc = ldap_xxx(..); # any ldap callmy $errstr = ldap_err2string($rc);print "Error was: $errstr";

Connection Management Functions

ldap_open(host, port)Returns:

An opaque connection handle (an LDAP* pointer).

Parameters:

host: Name of the network host where the LDAP directory resides.

port: Ignored in InterMail Kx.

Description:

Opens a connection to an LDAP server on a specific host and port.

Example:

$ldap_host = qx{uname -n};($LOGIN,$PASSWORD)=(’root’,’’);my $ld=ldap_open($ldap_host, 389);

ldap_simple_ bind_s(ld, login, password)Returns:

An LDAP status code.

Parameters:

ld: Connection handle returned by ldap_open.

login: String containing the login name.

LDAP Perl API


password: String containing the password.

Description:

Authenticates a user to the directory.

Example:

my $rc = ldap_simple_bind_s($ld,$LOGIN,$PASSWORD);

ldap_unbind(ld)Returns:


Parameters:


Description:

Disconnects and unbinds from the LDAP server.

Example:

$rc = ldap_unbind($ld);

Functions That Perform Operations on Entries

ldap_add_s(ld, dn, data)Returns:


Parameters:


dn: Distinguished name (DN) of the entry to be added.

data: Hash containing attribute names and values to be added.

Description:

Adds an entry to the LDAP directory.



Example:

# add a country$country="myowncountry";$country_dn="c=$country";$country_data={

’objectclass’=>[’country’],’c’=>[’USA’, ’US’, ’America’],’telephonenumber’=>[’1’],

};($dn,$data)=($country_dn,$country_data);$rc = ldap_add_s($ld,$dn,$data);

# add an organization in that country$org_dn="o=’SwampLand Ltd.’, $country_dn";$org_data={

’objectclass’=>[’top’, ’organization’],’o’=>[’SwampLand Ltd.’, ’SLD’],’telephonenumber’=>[’(781)555-5555’],

};$rc = ldap_add_s($ld,$org_dn,$org_data);>

ldap_modify_s(ln,dn, data)Returns:


Parameters:


dn: Distinguished name (DN) of the entry to be modified.

data: Hash containing attribute names and values to be modified.

Description:

Modifies one or more attributes on an entry.

Example:

$new_country_data={# Notice ’r’ for REPLACE’telephonenumber’ => {’r’ => [123]},

};$rc = ldap_modify_s($ld,$dn,$new_country_data);

ldap_delete_s(ld, dn)Returns:


Parameters:


dn: Distinguished name (DN) of the entry to be deleted.

LDAP Perl API


Description:

Deletes an entry from the LDAP directory.

Example:

$rc = ldap_delete_s($ld,$country_dn);

ldap_modrdn_s(ld, dn, newrdn)Returns:


Parameters:


dn: Distinguished name (DN) of the entry to be modified.

newrdn: New relative DN (RDN) for the entry.

Description:

Modifies the RDN of an entry.

Example:

$new_c="c=IownFrance";$rc = ldap_modrdn_s($ld,$country_dn,$new_cn,0);

ldap_rename_s(ld, dn, newrdn, newbase, deleteold)Returns:


Parameters:


dn: Distinguished name (DN) of the entry to be renamed.

newrdn: New relative DN (RDN) for the entry.

newbase: New base DN under which the entry is to be added.

deleteold: 0 = Do not delete the old entry; 1 = Delete the old entry.

Description:

Renames an entry in the LDAP directory.



Example:

$new_c1="c=anewcountry";$rc = ldap_rename_s($ld,$dn,$new_c1,$org_dn,0)’);

ldap_search_s(ld, dn, scope, filter, attrs, attrsonly, result)Returns:


Parameters:


dn: Distinguished name (DN) of the entry from which the search is to start.

scope: Search scope (LDAP_SCOPE, LDAP_SCOPE_ONELEVEL, LDAP_SCOPE_SUBTREE)

filter: LDAP search filter.

attrsonly: 0 = Return attributes and values; 1 = Return attribute names only.

result: Opaque pointer containing search results; used in later LDAP calls.

Description:

Searches the LDAP directory.

Example:

$start_from=$org_dn;$filter="(objectclass=*)";$attrs=[];$result;$rc = ldap_search_s($ld,$start_from,LDAP_SCOPE_ONELEVEL,$filter,$attrs,0,$result);

ldap_count_entries(ld, result)Returns:

An integer.

Parameters:


result: Opaque pointer returned by a previous call to ldap_search_s.

Description:

Returns a count of the number of entries returned by the last search operation.

LDAP Perl API


Example:

$count=ldap_count_entries($ld,$result);print "\$count=$count\n";

ldap_get_all_entries(ld, result)Returns:


Parameters:



Description:

Returns an array containing all entries found in the last search operation.

Example:

%record = %{ldap_get_all_entries($ld,$result)};my @dns = (sort keys %record);print $#dns+1 . " entries returned.\n";

%r=%{ldap_get_all_entries($ld, $result)};print "Entries are:";for $n (sort keys %r) {

print "<$n>\n";for $v (sort keys %{$r{$n}}) {

print ":\t$v\n";}

}

Access Control Information FunctionAccess control information (ACI) exists as a set of rules within the directory. Each rule specifies permissions for a set of users accessing a targeted set of LDAP entries. Within a rule, permissions may apply to every attribute, to attributes within a particular object class, or to a single attribute.

ldap_apply_aci_rule_sParameters:


bindDn: Distinguished name (DN) of the binding entry. You may specify LDAP_DIT_ROOT or LDAP_ACI_SELF here.

bindType: Type of bind DN (such as subtree or group).

targDn: DN of the target entry. You may specify LDAP_DIT_ROOT here.

objclass: Optional object class name. If not set, this must be null.

attr: Optional attribute name. If not set, this must be null.



realm: Scope of the entry named by targDn or its children.

perms: A summation of allowed permission values (for example, LDAP_ACI_ALLOW_READ).

Description:

Creates or modifies an ACI rule. Sets the permissions for the user(s) identified by bindDn, accessing the entries identified by targDn, objclass, attr, and realm. If a rule already exists for the specified bindDn, bindType, targDn, objclass, attr, and realm, the permissions are adjusted accordingly. If after adjustment all permissions are set to DEFAULT, the rule is removed.

Synopsis:

int ldap_apply_aci_rule_s( LDAP * ld, const char * bindDn, const LDAPBindType bindType, const char * targDn, const char * objclass, const char * attr, const LDAPRealm realm, const LDAPPerms perms);

Memory Management Function

ldap_msgfree(result)Returns:


Parameters:


Description:

Frees memory associated with a result returned by ldap_search_s.

Example:

$rc = ldap_msgfree($result)


9Log Events

This chapter describes the log events that occur in InterMail. These descriptions help you understand why these events occur and what (if anything) you can do to control or stop errors.

This chapter presents the log events in logical groups (according to server/process/functionality) arranged alphabetically. For each log event, the following information appears:

• Event Name: The actual log event name that the log file reports.

• Description: A short synopsis of the message.

• Parameters: Parameters, arguments, or variable names in the description of the event.

• Cause: The specific reason(s) why an event occurred.

• Effect: The effect that an event has on the operation of InterMail, including the severity level.

• Actions: The suggested course of action to correct the problem, or an action to minimize the effect of the problem.

For information about how logging occurs in InterMail, types of log files, and how to view log files, see Chapter 12 of the InterMail Kx Operations Guide.



Account Log Events

,��.��

,��.��!

Description: The user is entering a bad password.

Parameters: None.

Cause: This happens because the user forgets his or her password, enters a wrong password, or the password has changed. The user name is in the log entry as an additional tagged argument, such as [email protected]. Passwords (even incorrect ones) do not appear in the log, for security reasons. Use the program imcacheread to verify returns from the ISD.

Effect: The event is of informational severity.

Action(s): Generally, no action is necessary. Users eventually remember the correct password.

Description: Maximum invalid password attempts from user.

Parameters: None.

Cause: None.


Action(s): This message is to discourage people trying to crack POP passwords by repeated authentication attempts. When you see this notification message, first determine if this is a malicious attempt to crack a POP password or a problem with a user’s email configuration. If it is the latter, contact the user and assist as needed. Otherwise, report this to a person in charge of network security.

Log Events


,��.��!,��

,��.��!)��

Description: Reached maximum number of IP addresses making invalid password attempts.

Parameters: None.

Cause: None.


Action(s): This message is to discourage people trying to crack POP passwords by repeated authentication attempts. When you see this notification message, first determine if this is a malicious attempt to crack a POP password or a problem with a user’s email configuration. If it is the latter, contact the user and assist as needed. Otherwise, report this to a person in charge of network security.

Description: User reached maximum delay.

Parameters: None.

Cause: This message is to discourage people trying to crack POP passwords by repeated authentication attempts. The POP server makes time delays before the standard –Err reply to repeated bad password attempts. Each unsuccessful authentication attempt causes this delay to increase until it reaches a maximum delay that the configuration database defines.


Action(s): When you see this message, first determine if this is a malicious attempt to crack a POP password or a problem with a user’s email configuration. If it is the latter, contact the user and assist as needed. Otherwise, report this to a person in charge of network security.



,��.��!��

,��.��!-��

,��)��'��(�)��

Description: Maximum number of unsuccessful logon attempts in the defined time span.

Parameters: None.

Cause: This message is to discourage people trying to crack POP passwords by repeated authentication attempts.



Description: Maximum number of users making invalid password attempts.

Parameters: None.

Cause: This message is to discourage people trying to crack POP passwords by repeated authentication attempts.



Description: The ISD is down.

Parameters: None.

Cause: The ISD is down and this client cannot contact it.

Effect: The event is of error severity for the MTA and warning for MSS, POP and IMAP.

Action(s): Look in the log for related messages about failure to contact the ISD.

Log Events


,��)��'��(� ��

,��)��'��(�-�*��

Description: In the program imboxcopy, there is a request to the ISD to get the status, host, and mailbox name for the user userName, but it receives a status other than NULL_PASSWORD or MAINTENANCE. Because of this, it does not move the mailbox.

Parameters: userName: the name of the user.

reason: the reason for denying the request.

Cause: The return status is either:

• UNKNOWNUSER: the user name given has no directory entry.

• BADPASSWORD: since imboxcopy does not submit passwords, this should never happen, and indicates a problem with the communication channel or the ISD.

• FORWARDTO: the user is forwarding mail. Though not currently supported, it may be in the future.

• FAILED: the call to the ISD is failing.

• INACTIVE: the account for the user is inactive

Effect: None.

Action(s): Access the ISD directly using the program imcacheread to verify the results reported in the log.

Description: The information received from the ISD has either the hostname or the message store name null.

Parameters: hostname: name of the MSS host being returned by the ISD.

mailboxName: name of the message store being returned by the ISD.

status: status from ISD.

Cause: There are no known causes for this. It should never happen.

Check the imdirserv log for anomalies.

Effect: The event is of warning severity.

Action(s): Use imcacheread to verify returns from the ISD.



9,��

,��

,��#��

Description: An account has forwarding turned on, but one or more forwarding addresses are unparseable.

Parameters: addr: primary SMTP address for the account.

fwda: (invalid) forwarding information that is returned.

Cause: Forwarding information for the account is misconfigured.

Effect: The event is of major severity (Error), but this only affects the account in question. It means no mail is delivered to that account until this is fixed.

Action(s): Correct the forwarding information for the account in question.

Description: An account has forwarding turned on, but no forwarding info.

Parameters: addr: primary SMTP address for the account.

Cause: Account information is misconfigured.

Effect: The event is of major severity (Error). This only affects the account in question. It means no mail is delivered to that account until this is fixed.

Action(s): Fix the account.

Description: A ForwardInfo lookup is failing.

Parameters: None.

Cause: The imdirserv cannot obtain information from the authoritative directory service, because of a cache lookup error.

Effect: The event is of major severity (Error).

Action(s): Rebuild the Directory server using imdirsync.

Log Events


,��$�

,��,��

,��

Description: The imdirserv is returning information indicating that the mail for this user should be forwarded on to another address, but it is doing so using an old protocol which is no longer supported. Matches MTADoesntHandleForward.

Parameters: None.

Cause: This indicates mismatched executables, and is a configuration problem.


Action(s): Check to make sure all executables are the original versions as installed.

Description: A user is attempting to retrieve mail through the IMAP server, but the user account does not have IMAP authorization.

Parameters: None.

Cause: The user does not have permission to use the IMAP server.


Action(s): Verify that the user has authorization to use IMAP.

Description: Mailbox is currently inactive.

Parameters: None.

Cause: The imdirserv returns a status for this user indicating that this mailbox is currently inactive. The system cannot deliver mail to or read mail from inactive mailboxes.


Action(s): Contact the mail system administrator to find out why the mailbox is inactive.



,��-��

,��*��

,��

Description: UserName does not exist in the Integrated Services Directory.

Parameters: recipient: the address of the invalid recipient.

Cause: The userName is not in the Integrated Services Directory, and thus is not valid at this site.


Action(s): None.

Description: Directory Server lookup is failing.

Parameters: None.

Cause: The imdirserv cannot obtain information from the authoritative Integrated Services Directory, because of a cache lookup error.

Effect: The event is of major severity.

Action(s): Rebuild the Directory Server using imdirsync.

Description: Cannot access mailbox because it is in a maintenance mode.

Parameters: None.

Cause: A maintenance program (such as imboxmove) has exclusive access to the mailbox and there is no other access until that program finishes with it.


Action(s): • Wait a while and try again.

• If the status does not change within a reasonable period, check to see if someone has forgotten to take the account out of maintenance status.

Log Events


,��

,��-��

,��/�(��

Description: The user is not allowed to connect to the server via the specified interface address.

Parameters: addr: The address of the interface to which the client is connected.

Cause: The user’s COS attributes pref_popaccess (or popssl, imap, or imapssl) does not allow him to access the service through the specified interface. If the COS attributes is set to trusted and the interface is not listed in the trustedInterfaces configuration key then the user will be denied access.


Action(s): • Verify that the user is authorized to use the server in question.

• Verify that the host’s trustedInterfaces configuration key is correctly setup.


Parameters: None.



Action(s): None.

Description: A user entry from the Directory Server indicated forwarding, an inactive account, or an account undergoing maintenance.

Parameters: None.

Cause: This should never appear in a log file.


Action(s): None.



,��!��&��!

,��!��

Description: While reading the popFilter configuration during application initialization, it finds a substitution rule with an empty or invalid regular expression.

Parameters: substitution rule: the rule, in the form s/pat/rep/opts.

Cause: The popFilter configuration must contain one or more rules of the form sXpatXrepXopts, where X can be any character that is not in pat or rep. The pat component is a POSIX regular expression, which cannot be empty, and must conform to the syntax for regular expressions.

Effect: The event is of minor severity. It ignores the popFilter substitution rule containing the invalid regular expression. This causes some POP and/or IMAP users to have difficulty connecting to their mailbox.

Action(s): Edit the configuration value to correct the syntax or remove the rule.

Description: While reading the popFilter configuration during application initialization, a substitution rule at the specified character position does not contain three separators.

Parameters: separator count: the number of separators actually found after the specified character offset.

character position: the offset from the start of the configuration value where the error is located.

Cause: The popFilter configuration must contain one or more rules of the form sXpatXrepXopts, where X can be any character not in pat or rep. The character following the initial “s” is interpreted as a separator between the pat, rep, and opts components, and all three separators are necessary to form a valid substitution rule.

Effect: The event is of minor severity. It ignores all popFilter substitution rules after the specified position in the configuration value. This causes some POP and/or IMAP users to have difficulty connecting to their mailbox.

Action(s): Edit the configuration value to correct the syntax

Log Events


,��!��

,��,��

,��.��

Description: While reading the popFilter configuration during application initialization, a substitution rule is at the specified character position that does not begin with “s”.

Parameters: character position: the offset from the start of the configuration value where the error was.

Cause: The popFilter configuration must contain one or more rules of the form sXpatXrepXopts, where X can be any character not in pat or rep. The initial “s” is necessary to form a valid substitution rule.

Effect: The event is of minor severity. It ignores all popFilter substitution rules after the specified position in the configuration value. This causes some POP and/or IMAP users to have difficulty connecting to their mailbox.

Action(s): Edit the configuration value to correct the syntax.

Description: A user is attempting to retrieve mail through the POP server, but the user does not have authorization for POP use.

Parameters: None.

Cause: The user does not have permission to use the POP server.


Action(s): Verify that the user has authorization to use the POP server.

Description: The user is entering an invalid password.

Parameters: None.

Cause: A user is entering a bad password for his or her mail account.


Action(s): Usually there is nothing to do. The user eventually remembers his or her password or gets a new one.



,��,��

,��,��

,��-�*��-��

Description: A user attempted to retrieve mail through the imap server using SSL, but the user’s account is not authorized for imap use with SSL.

Parameters: None.

Cause: The user is not allowed to use the imap server with SSL.


Action(s): Verify that the user is authorized to use imap with SSL.

Description: A user is trying to retrieve mail through the POP server using SSL, but the user's account is not authorized for POP use with SSL.

Parameters: None.

Cause: The user does not have permission to use SSL with the POP server.


Action(s): Verify that the user has authorization to use SSL with the POP server.


Parameters: None.



Action(s): None.

Log Events


Configuration Log Events

'��.��'(��*��

Description: A bad checksum is in the configuration file.

Parameters: badChecksum: the bad MD5 checksum found in the configuration file.

filename: the path to the configuration file.

Cause: This indicates that something other than the imconfedit utility made changes. The message is merely informational, but if the user introduced syntax errors, the file may not read in.

Effect: The event is of critical severity.

If the host’s configuration file ($INTERMAIL/config/config.db) has syntax errors, all InterMail applications fail to initialize and do not execute.

Action(s): • If the system can read the configuration file successfully in spite of the bad checksum, then no action is necessary. In this case, to stop the continual complaining log entries, copy the config.db to another file (for instance, config.bad). Then use imconfcontrol to install the new config.bad file and, in the process, calculate and write a new checksum.

• If there are syntax errors, log entries indicate the nature of the error as well as the line number in the file.

• In any case, the system administrator may want to investigate to determine what is causing the problem.



'��.��

'��'(��,��

'��'(��

Description: There is a bad key in the configuration file.

Parameters: badKey: the bad key in the configuration file.


errorLine: the line number at in the configuration file.

Cause: This indicates that there is a bad key in the configuration file. Keys are of the form ///. One of the first three slashes is missing.


The named configuration file changed in a way that introduced syntax errors. If this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.

Action(s): Fix the configuration file manually using a text editor.

Description: The configuration server imconfserv is to read and assess the impact of a configuration database file.

Parameters: extension: the extension of the config.db file

Cause: Invoking imconfcontrol.

Effect: None.

Action(s): None.

Description: The configuration server imconfserv is to read and install a new configuration database file.

Parameters: None.

Cause: Invoking imconfcontrol.

Effect: None.

Action(s): None.

Log Events


'��'��'��

'��'��

Description: A client program is connecting to the configuration server.

Parameters: clientProgram: the client program connecting to imconfserv.

clientHost: the host on which the client program is running.

timeStamp: the timestamp of the client’s configuration keys.

Cause: A client program is connecting to the configuration server.

Effect: None.

Action(s): None.

Description: The value of a port number configuration key allows various servers and/or various hosts to use it. The system does not allow this.

Parameters: portNumber: the port number value of the configuration key.

parmKey: the full key of the parameter.

Cause: A configuration key whose name ends in port (and which presumably specifies a listening port) has a host name of * or a program name of common or both. The parameter is host- and server-specific, such as /hostA/POPserv/pop3Port.

Effect: The system rejects the attempt to change the configuration data, and no parameters change.

Action(s): None.



'��'��&��

'��)��

Description: The value of a port number configuration key allows various servers and/or various hosts to use it. The system does not allow this.

Parameters: firstPortNumber: the first port number of the range of the configuration key.

lastPortNumber: the last port number of the range of the configuration key.

parmKey: the full key of the parameter.

Cause: A configuration key whose name ends in port (and which presumably specifies a listening port) has a host name of * or a program name of common or both. The parameter is host- and server-specific, such as /hostA/POPserv/pop3Port.

Effect: The system rejects the attempt to change the configuration data, and no parameters change.

Action(s): None.





Cause: This indicates that there is a bad key in the configuration file.

Keys are of the form ///. Key components consist only of letters, numbers, and the characters /, ., and _. The component can also be * (meaning all hosts). The component violates this rule.

Effect: The event is of critical severity. The named configuration file has syntax errors, and if this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.


Log Events


'�� -��

'��!��

Description: The operation of assessing the impact of a new set of configuration keys has ended.

Parameters: oldTimeStamp: the timestamp of the previous dictionary.

newTimeStamp: the timestamp of the new dictionary.

numImpacts: the number of parameter changes that had a significant impact.

Cause: An invocation of imconfcontrol causes this. If the number of impacts (changes that the program cannot handle while continuing to run) is non-zero, then the server’s internal state regarding parameters does not change. In this case, imconfcontrol indicates the extent of the problem to the user of imconfcontrol or imconfedit.

Effect: None.

Action(s): None.

Description: An attempt to accommodate a change in a configuration key is failing.

Parameters: paramName: the name of the configuration key.

hostName: the host name for which the system sought the parameter value.

programName: the program name for which the system sought the parameter value.

Cause: A function called to accommodate a change in the configuration key fails or raises an exception.

Effect: The behavior of the program does not change with respect to the parameter that changed.

Action(s): Restart the program to accommodate the change.



9'��/�(��

'��

Description: An MSS is already listening on this port. Since only one process can be listening on any port, the second MSS refuses to come up until the first MSS relinquishes the port.

Parameters: port: the port number on which this process is listening.

Cause: Ordinarily, the .pid files indicate which MSS ports are in use, and imctrl does not attempt to launch a new MSS process whose port conflicts with a running MSS process. If the .pid files are missing, or a MSS process fails to stop when requested, then imctrl is unable to detect the problem and launch a conflicting MSS.

Effect: The event is of critical severity. Since the MSS that currently owns the port should have terminated previously, the MSS no longer be functions properly. At a minimum, the process is not aware of any recent changes to the system configuration. This results in degraded system performance or failure to communicate with other parts of the system.

Action(s): • Check the MSS processes on this machine.

• If the MSS processes are already running correctly, do nothing.

• If there is a problem, use imctrl to stop and restart the MSS processes.

• If this is not successful, you may have to use the ps command to find out which servers are running, then use kill -9 to stop them manually.

Description: The Configuration Server is not successfully installing the new configuration information.

Parameters: None.

Cause: The program imconfcontrol is trying to install a new set of configuration keys.


Action(s): Read the imconfserv log to find out what the problems are.

Log Events


'��

'��"��

Description: The Configuration server successfully installed the new configuration information.

Parameters: None.

Cause: The program imconfcontrol installed a new set of configuration keys.

Effect: The effect depends upon which parameters are changed.

Action(s): None.





Cause: This indicates that there is a bad key in the configuration file.

Keys are of the form ///. Key components consist only of letters, numbers, and the characters /, ., and _. The component can also be * (meaning all hosts). The component is violating this rule.


The named configuration file has changed in a way that introduced syntax errors. If this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.




'��

'��





Cause: This indicates that there was a bad key in the configuration file.



The named configuration file has syntax errors, and if this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.






Cause: This indicates that there was a bad key in the configuration file.



The named configuration file has been modified in a way that introduced syntax errors, and if this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.


Log Events


'��,��

'��)��

'�� !��

Description: The Configuration server’s copy of the config.db file is adding a key/value pair.

Parameters: parmKey: the name of the configuration key added.

parmValue: the value of the configuration key added.

Cause: Someone is using the program imconfcontrol to add this key.

Effect: Varies widely depending on the particular parameter.

Action(s): None.

Description: A key/value pair from the Configuration Server’s copy of the config.db has been deleted.

Parameters: parmKey: the name of the deleted configuration key.

Cause: Someone is using imconfcontrol to delete this key.

Effect: Varies widely depending on the particular parameter.

Action(s): None.

Description: The license for your InterMail installation has expired.

Parameters: None.

Cause: The license has expired per the "expiration" component of the license.

Effect: The event is of critical severity. Mail will continue to be delivered and received, but will have an appended header that indicates that the mail server is running an expired license. The SMTP banner will also indicate that the license has expired.

All provisioning will be blocked; no new accounts can be created, no changes to existing accounts can be made.

Action(s): Contact your InterMail vendor and get a new license.



'�� !��

'��*��

Description: The license for your InterMail installation will expire soon. The expiration time is defined by the config key licenseWarnThresholdDays.

Parameters: None.

Cause: The license will soon expire per the "expiration" component of the license.

Effect: None. There is no effect on service. This is a warning that a new license should be obtained soon. To remove the warning, reduce the config key licenseWarnThresholdDays.

Action(s): Contact your InterMail vendor and get a new license or reduce licenseWarnThresholdDays.

Description: The application is unable to obtain a lock on the configuration file.

Parameters: None.

Cause: Another application has the configuration file locked for its use, or an application has been exited or killed before the configuration file has a chance to delete the lock file.

Effect: No configuration changes are possible with the file locked.

Action(s): • Examine the contents of the file $INTERMAIL/config/config.db.lk.pid. It contains the process id of the process that created the lock file. Using ps(1) (on UNIX) or other appropriate tools, determine if that process is still running. If not, delete the config.db.lk and config.db.lk.pid files and run the original application again, if necessary.

• If the process is still running, however, it may in fact be in a comatose state. Explore other means to ascertain the status of the running program. If appropriate, kill the process and remove the lock files to get around the impasse.

Log Events


'��

'��.��*��@

'��.��*��A

Description: An error is occurring while reading the configuration.

Parameters: None.

Cause: Corrupt configuration file.


No InterMail application that uses the configuration database runs.

Action(s): Replace the configuration file with a copy known to be good.

Description: There is no left bracket, which indicates the beginning of the parameter value.

Parameters: key: the key in the configuration file.


errorLine: the line number in the configuration file.

Cause: Someone is editing the file incorrectly.


The named configuration file has been modified in a way that introduced syntax errors, and if this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute.


Description: The same key (parameter name) appears twice in the configuration file.




Cause: Someone is incorrectly editing the file.

Effect: None. The last value in the file for a key overrides all preceding values.




'��'��

'��&�7��

Description: There is no colon, which terminates a parameter name.




Cause: Someone is incorrectly editing the file.


The named configuration file is modified in a way that introduces syntax errors, and if this is the host’s main configuration file ($INTERMAIL/config/config.db), all InterMail applications fail to initialize and do not execute. In this case, manual correction on the file using a text editor are necessary.


Description: A necessary parameter is missing from the config.db file.

Parameters: parmName: the parameter.

Cause: An ill-advised edit session may be at fault. (Note that InterMail as installed has all the necessary parameters.)

In any case, consult the documentation for the parmName and re-edit the config.db, giving it an appropriate value.

Effect: The event is of serious severity, but depends on the particular parameter.

Action(s): Put the required parameter back in the config.db.

Log Events


'��0�$��

'��'��

Description: The configuration initialization routine has a program name longer than sizeLimit characters. No known InterMail program has, or will have, names this long.

Parameters: moduleNameSize: the size of the module.

namesizeLimit: the limit on the size of the module name.

Cause: The configuration initialization routine has a program name longer than 256 characters.

Effect: The event is of critical severity. The program will not run.

Action(s): If you have renamed an InterMail program with a new name that is longer than 256 characters, then choose a shorter name. Contact your InterMail vendor.

Description: There was no catalog file for national language support.

Parameters: messageCatalogName: the name of the message catalog.

file.language: the language selected.

pathSearchList: the list of directories to search for catalog.

Cause: • The NLSPATH or LANG environment variable is set incorrectly.

• The NLS file is missing, or does not have read permission.

Effect: The event is of minor severity. A few operations will fall back to hard-coded default strings instead of using the value specified in the NLS file. This could result in slightly different text for error messages and other informational messages.

Action(s): Check that the InterMail NLS files are correctly installed and readable.



'��'��

'��&��

Description: There was no message catalog specified using an absolute pathname, or it was unreadable.

Parameters: messageCatalogPath: full pathname to the message.

catalog.systemErrorString: system error from the stat call.

Cause: • The NLSPATH or LANG environment variable is set incorrectly.

• The NLS file is missing, or does not have read permission.

Effect: The event is of minor severity. A few operations will fall back to hard-coded default strings instead of using the value specified in the NLS file. This could result in slightly different text for error messages and other informational messages.

Action(s): Check the values of the NLSPATH environment variable. Remove any components that do not contain the %L and %N substitution fields. Check the values of the LANG environment variable. Try setting it to “C”, or leaving it unset. Check that the InterMail NLS files are correctly installed and readable.

Description: The Configuration Server has accepted a connection from a program with an out-of-date set of parameter values with the timestamp shown. The configuration server has transmitted a newer set of values to the program.

Parameters: programName: the name of the program connecting.

hostName: the name of the host the program is running on.

timestamp: the timestamp of the new set of configuration keys.

Cause: A client connecting to the configuration server.

Effect: None.

Action(s): None.

Log Events


'��'��$��

'��)��

'��"��

Description: There was a request that uses connection tracking from a server that does not support it. Connection tracking monitors the number and type of RME clients connected to a server.

Parameters: None.

Cause: This version of the MSS compiled without connection tracking.

Effect: The event is of warning severity. Some administrative features will not be available with the current release.

Action(s): None.

Description: The configuration value for domainName is missing from the configuration database.

Parameters: None.

Cause: This indicates that the configuration database contains no domainName key.

Effect: The event is of warning severity. Some administrative features are not available with the current release.

Action(s): None.

Description: The configuration file had no header and no checksum.

Parameters: fileName: the path to the configuration file.

Cause: Either this configuration file not written by an InterMail application or user subsequently modified it.

Effect: This message is informational. If no other errors occur, there will be no impact on service.

Action(s): None.



'��-��

'��

Description: An update request is made and no update is required.

Parameters: None.

Cause: • The configuration file at the requesting host is the same as the configuration file at the configuration update server host.

• An attempt to update the configuration is made at the host already running the master copy of the configuration.

Effect: This event is of informational severity indicating that the configuration is up to date.

Action(s): None

Description: A non-standard port appears in the config.db file.

Parameters: parmName: the parameter specifying the non-standard port.

progName: the program portion of the parm key.

hostName: the hostname portion of the parm key.

standardPort: the standard value for this port.

nonStandardPort: the non-standard value for this port.

Cause: This may not be a problem, but it is unusual. If, for example, the pop3Port is 8050, instead of the usual 110, then POP clients not configured for this unusual situation will try to connect to 110 and fail.

Effect: If clients do not know about the change, they will be unable to connect to the server.

Action(s): Check to see if the unusual port assignment was intentional or not.

Log Events


'��,'��"��

'��/�(��"��"��*��

Description: The host hostName has no config.db entries at all, and is probably incorrect.

Parameters: hostName: the host name.

Cause: Usually an incorrect host name.

Effect: No major impact.

Action(s): None.

Description: An InterMail package installing on the host hostname.

Parameters: hostName: the hostname where a package installation is taking place.

Cause: An InterMail package installing on the host hostname.

Effect: No changes to the master config.db are possible until the installation completes. Clients reading the config.db information will continue using the local copy of config.db. As soon as the installation completes, the system will notify running servers of any config.db changes. If the installation terminates prematurely, there will be no changes.

Action(s): None.



'��'(��

'��

Description: The value of a configuration key changed in a running program.

Parameters: hostName: name of the host for the configuration key.

programName: name of the program for the configuration key.

paramName: name of the configuration key.

oldValue: the previous value of the parameter.

newValue: the new value of the parameter.

oldTimeStamp: the timestamp of the previous dictionary.


Cause: A program received a new set of configuration keys from the configuration server (imconfserv) and the configuration key paramName changed its value.

Effect: The program will begin using the new value of the parameter.

Action(s): None.

Description: An bad key was found in the configuration file.

Parameters: badKey: The bad key found in the configuration file.

error: The problem with the key.

Cause: This indicates that a bad key was found in the configuration file. Most likely, the key was not specified in the required format. Refer to the manual for the proper specification of the key in question.

Effect: The configuration key may not be having the desired effect. Most likely InterMail is ignoring the key.

Action(s): Fix the configuration key using imconfedit.

Log Events


'��(

'��'��

Description: The Configuration Server has pushed a new set of configuration keys to the server programName running on host hostName.

Parameters: newTimeStamp: the timestamp of the new dictionary.

programName: the name of the server program.

hostName: the host the server program is running on.

Cause: Running imconfcontrol caused this.

Effect: None.

Action(s): None.

Description: Two or more config.db parameters specifying port numbers are in conflict.

Parameters: portNumber: the number of the port in conflict.

serverName: name of the server that would use this port.

hostName: name of the server’s host.

parm: the name of the parameter specifying the port.

scopeOfConflict: the scope of the conflict.

Cause: An inconsistency in the configuration data might cause two or more servers to try to listen on the same port. There will be a log entry for each parameter in conflict.

If the scope of conflict is “a conflict on the same host”, then this is clearly always a serious conflict.

If the scope is “a conflict within a failover group”, then the conflict will cause problems if and when the hosts mentioned are actually running on the same machine.

If the scope is “a conflict among all hosts”, then all hosts are in the same failover group and thus any two uses of the same port number constitute a conflict. The /*/common/failoverGroups configuration key defines failover groups, where each value is of the form host1/hostb/hostc. If the value is “all”, then all hosts are in the same failover group.

Effect: The system will reject the attempt to change the configuration data, and no parameters will change.

Action(s): None.



'��'��&��

'��(��,��&�7��

Description: Two or more config.db parameters specifying port numbers or port number ranges are in conflict.

Parameters: firstPortNumber: the first port number of the range in conflict.

lastPortNumber: the last port number of the range in conflict.

serverName: name of the server that would use this port.

hostName: name of the server’s host.

parm: the name of the parameter specifying the port.

scopeOfConflict: the scope of the conflict.

Cause: There is an inconsistency in the configuration data whereby two or more servers would be trying to listen on the same port. There will be a log entry for each parameter in conflict.

If the scope of conflict is “a conflict on the same host”, then this is clearly always a serious conflict.

If the scope is “a conflict within a failover group”, then the conflict will cause problems if and when the hosts mentioned are actually running on the same machine.

If the scope is “a conflict among all hosts”, then all hosts are in the same failover group and thus any two uses of the same port number constitute a conflict. The /*/common/failoverGroups configuration key defines the failover groups, where each value is of the form host1/hostb/hostc. If the value is “all”, then all hosts are in the same failover group.

Effect: The system will reject the attempt to change the configuration data, and no parameters will change.

Action(s): None.

Description: A path and a filename are required

Parameters: pathName: the path name.

fileName: the file name.

Cause: None.

Effect: This event is of critical severity. The application does not run.

Action(s): Contact your InterMail vendor.

Log Events


'��()��,��0�

'��*

'��'��"��

Description: An array provided to the configuration initialization routine was of length arraySize when a minimum size of minSize is necessary.

Parameters: arraySize: the size of the array.

minSize: the minimum allowed size of the array.

Cause:

Effect: The event is of critical severity. The application does not run.


Description: Configuration Server locked, unlocked, or reverted the host/pid mentioned.

Parameters: processID: the id of the process that performed the action.

HostName: the host that has performed the action.

Action: the action performed.

Cause: Typically, this happens from an imconfedit session, but the installation process also locks the Configuration Server.

Effect: None.

Action(s): None.

Description: Server serverName not configured to run on the host hostName; that is, there is no entry like /hostName/sysadmin/serverName_run.

Parameters: serverName: the server name.

hostName: the host name.

Cause: Usually an incorrect host or server name.

Effect: None.

Action(s): None.



'��*��

'��-��

'��+��)��

Description: imconfcontrol has attempted to end an install but hostName was not an installing host.

Parameters: hostName: the hostname that imconfcontrol used.

Cause: A mistaken use of the -endInstall or -abortInstall options of imconfcontrol on a host that did not previously use –startInstall.

Effect: None.

Action(s): None.

Description: The operation of assessing the impact of a new set of configuration keys has begun.

Parameters: oldTimeStamp: the timestamp of the previous dictionary.


Cause: The program has received a new set of configuration keys from the configuration server and has begun to assess the impact. imconfedit began this action.

Effect: None. ConfParmChanged reports individual parameter changes.

Action(s): None.

Description: A ConfigParmDict with keysRequired keys constructed for paramName, but the call to getString() provided only keysProvided keys.

Parameters: keysRequired: the number of keys required.

keysProvided: the number of keys provided in the getString()call.

paramName: the name of the configuration key.

Cause: None.

Effect: The program will not be able to get the correct value for the configuration key. The results are not predictable.


Log Events


Database Log Events

.��,��

.��.��)��

Description: The database application environment cannot initialize for the directory directory: error code code (string).

Parameters: directory: name of the database directory.

code: error code given for the failure.

string: text error string associated with the error code.

Cause: A complete failure of the database layer to initialize itself successfully.

Effect: The server cannot start.

Action(s): Check the logs and the general condition of the machine. If this error persists, it may be necessary to restore from the last backup to recover. Contact your InterMail vendor.

Description: Badly formatted data was found in the database file filename.

Parameters: filename: name of the database file.

Cause: While stepping through data in the database, the system found an apparently corrupted record.

Effect: The database operation is aborted.

Action(s): Check the logs for other errors, and check the general condition of the machine. This is an indication of some kind of data corruption or problem with the disk. It may be necessary to go back to the last backup. Contact your InterMail vendor.



.��'��'��

.��'��/��

Description: An attempt to create a cursor in the file filename failed with error code code (string).




Cause: An attempt to create a cursor in the file filename failed with the error code code (string).

Effect: A potentially serious denial of service, since database operations cannot be performed as expected.


Description: An attempt to perform a cursor operation operation in the file filename failed with the error code code (string).


operation: text representation of the attempted operation.



Cause: An attempt to perform a cursor operation operation in the file filename failed with the error code code (string).



Log Events


.��)��

.��)��

.��)��*)��

Description: The event described by message occurred while the system was accessing the database.

Parameters: message: name of the message.

Cause: This is an informational note concerning some operation of the database.

Effect: None.

Action(s): Contact your InterMail vendor if necessary.

Description: A database inconsistency of type string1 was found as indicated by string2 and string3.

Parameters: string1: the type of inconsistency found.

string2: information specific to the problem.

string3: information specific to the problem.

Cause: Some kind of mismatch of expected data in the Message Store server (MSS) was found. As much information as could be determined is given in the message.

Effect: Data for the specified message store is not available.

Action(s): Contact your InterMail vendor. It may be necessary to restore the database from backup, since this data corruption cannot be directly fixed in most cases.

Description: Recoverable deadlock condition was detected (file=%s, op=%s).


operation: text representation of the attempted operation.

Cause: The system recognizes a deadlock but can recover from it automatically.

Effect: None.

Action(s): Investigate persistent occurrences of this error for cause, and scan the logs for other abnormal behavior.



.��)��

.��/��

Description: An attempt to delete a record from the file filename failed with error code code (string).




Cause: An attempt to delete a record from the file filename failed with error code code (string).

Effect: Possible side effects.

Action(s): Check the file permissions and all normal system checks, and restart the server in question. If this error persists, it may be necessary to restore from backup.

Description: The database file filename could not be opened.




Cause: The database file filename could not be opened.

Effect: The server is likely to fail, since it cannot access the proper data.

Action(s): Check the permissions and condition of the named file. If this error persists, it may be necessary to restore from backup.

Log Events


.��1��

.��!&��

.��!&��

Description: An attempt to get a record in the file filename failed with error code code (string).




Cause: An attempt to get a record in the file filename failed with error code code (string).



Description: An attempt to rebuild the index database was unsuccessful.

Parameters: first param: event that caused the rebuild to fail.

second param: name of the entry where the rebuild is failed.

Cause: An attempt to rebuild the index database was unsuccessful.

Effect: The imdirserv cannot start until the index database is successfully rebuilt.


Description: An attempt to rebuild the index database was successful.

Parameters: None.

Cause: An attempt to rebuild the index database was successful.

Effect: None.

Action(s): None.



.��

.��&��

.��)��(

Description: An attempt to initialize the database database failed.

Parameters: database: name of the database.

Cause: An attempt to initialize the database database failed.

Effect: The server cannot start.

Action(s): Check file permissions and the general condition of the machine. It may be necessary to restore from backup, since the database file cannot even be opened. Contact your InterMail vendor.

Description: The message information record for message message was not found.


Cause: A record for a message is missing.

Effect: The operation is aborted.


Description: The message ID for message message is inconsistent with the retrieved message.


Cause: When the system retrieved a message from the message store, it found that the message ID did not match the one stored in the database.

Effect: The message is not available.


Log Events


.��

.��.��*��

Description: An attempt to modify a record in the file filename failed with error code code (string).




Cause: An attempt to modify a record in the file filename failed with error code code (string).



Description: The server is starting up in backup mode, which probably means that backup mode was left on.

Parameters: None.

Cause: The server is starting up in backup mode, which probably means that backup mode was left on.

Effect: Disk space may eventually be exhausted for the host that the server is running on.

Action(s): Set the configuration key for the server, either /*/mss/backupMode or /*/imdirserv/backupMode, to false.



.��$!�,��

.��$!�'��

Description: An attempt to commit a transaction for the file filename failed with error code code (string).




Cause: An attempt to commit a transaction for the file filename failed with error code code (string).

Effect: Possibly none.

Action(s): Check the logs for other errors, and check the general condition of the machine. This could be an indication of database problems.

Description: An attempt to commit a transaction for the file filename failed with error code code (string).




Cause: An attempt to commit a transaction for the file filename failed with error code code (string).

Effect: The system may not be able to continue functioning, since it cannot write to the database.


Log Events


)�'��(�'��

)�'��(�)��

Description: Successfully connected to InterMail Directory database.

Parameters: None.

Cause: None.


Action(s): None.

Description: Disconnected from InterMail Directory Server.

Parameters: None.

Cause: The InterMail application lost its connection to the InterMail Directory Server. This could be due to network problems or because the database server is no longer running.

Effect: The event is of minor severity. New accounts created while the Directory database is unavailable will not be accessible, and modifications to existing accounts will not be visible, since the Directory Server will be relying on cached information.

Action(s): If this notice is not due to known problems with the network or the database server, check the application’s log file for more severe events.



)�)��

Description: While gathering messages together in the Message Store Server, the message identified by msgid appears to be corrupt. The osRef and size are given to assist in debugging the problem.

The event should never occur. Contact your InterMail vendor.

Parameters: osRef: the reference that caused the error.

size: the size of the item in question.

msgid: the message ID of the message in question.

Cause: A message in the MSS is not valid.

Effect: • The event is of major severity. If the error occurs more than once, the entire MSS may be effectively inoperative. Failure to determine the cause of the event and resolve it may lead to lost or corrupted messages.

• The event is of minor severity. The POP server may be unable to retrieve messages from the affected mailboxes.

Action(s): • Check /var/adm/messages (or your platforms equivalent system message log) for indications of machine problems.

• Check the popserv and MSS logs in general for any abnormal activity.

• If it is determined to be a programming error, contact your InterMail vendor.

Log Events


9)��(

)��)��

Description: Getting the value of config-key from the configuration database failed. This value specifies the location of the Directory Server file. The event only happens when launching the imdirserv process.

Parameters: config-key: configuration key where pathname to DB file resides.

Cause: • System not configured correctly.

• Configuration database not in the correct place.

• Configuration database corrupted.

Effect: The ISD will exit immediately, which may defer incoming mail and suspend POP access.

The effect will be minor if other imdirserv processes are still running, and if the configuration on the current host is set up to fall back to these servers.

The effect will be critical if no other imdirserv processes are running, or if fallback behavior not specified, since all Directory access will fail.

Action(s): • Verify system configured correctly.

• Verify configuration file not corrupted.

Description: During initialization, an application (usually the MSS) could not find a value for mssMessageFileDir in the InterMail configuration.

Parameters: None.

Cause: • Missing or corrupted config.db.

• Incorrect value for $INTERMAIL environment variable.

Effect: The event is of critical severity. The system defers all incoming mail destined for the MSS on the current host, and no mailboxes on the MSS are be accessible for reading.

Action(s): Verify that the installation and the configuration of the InterMail software are correct.



)��)��(

Description: The message-ID for message msgNum did not match the message-ID found in the message’s file-based storage.

Parameters: msgNum: the database serial number for the message.

Cause: • File system corrupted.

• Database corrupted.

Effect: The event is of minor severity. The message moves to an .ERROR folder in the customer's mailbox and the customer will be unable to retrieve it until you have fixed the problem. POP clients will usually abort the current session when the event occurs, but future sessions will not see the problem message.

Action(s): • Run imbadmsglist to get a list of all messages that currently require administrator attention.

• Recover the associated message files using file system backups and, if necessary, journal files.

• Run imbadmsgfix on the recovered files.

If the error occurs again, delete the message from the user's .ERROR folder and inform the user that a message lost. If this occurs frequently, verify the integrity of the database.

Log Events


)��$��

)��

Description: The name specified for a mailbox property was longer than the maximum length supported by this MSS schema.

Parameters: None.

Cause: None.

Effect: The current database operation will fail.


Description: Unable to find adequate storage for a new message with message-ID msgId in the message file system.

Parameters: msgId: the message-ID of a message.

Cause: • The mssMessageFileDir configuration value is incorrect.

• Disk storage exhausted, or some volumes not mounted.

• imbucketscreate has not run recently.

• The message is larger than any single volume can currently contain.

Effect: The event is of critical severity. The system will defer the message until space becomes available. However, if there is not space for one message, then there is a critical shortage of disk space that will prevent storing most other messages as well.

Action(s): • Verify that the value of mssMessageFileDir is correct and that the permissions for all files under this directory are correct.

• Verify that the crontab entry for imbucketscreate is correct and that the job has run recently. Check the date and examine the contents of the buckets file in the mssMessageFileDir directory.

• Verify that all appropriate message file systems are mounted and writable. If this is not the case, mount the file systems and run imbucketscreate.

• Check the size of the incoming message to see if it is reasonable. If it is not, check the configuration value for the MTA’s maximum acceptable message size.



)��'��'��

9)�$��)��'��

)�%��$��

Description: Number of pool client connections specified is invalid.

Parameters: None.

Cause: Configuration error. Check the configuration key imdirserv /dircacheConnections.

Effect: Minor, Critical. This causes Directory authorization services to be unavailable.


Description: There is only one instance of DirClientPool allowed.

Parameters: None.

Cause: None.

Effect: The event is of critical severity. This causes the process to exit.


Description: The value specified for a mailbox property was longer than the maximum length supported by this MSS schema.

Parameters: None.

Cause:

Effect: The event is of error severity. The current database operation will fail.


Log Events


Directory Cache Log Events

'��(�-��$��$��

Filter Log Events

��,��.��

Description: The cache update took an unusually long time to complete (update time seconds).

Parameters: update time: The time it took to update the cache.

Cause: Something is making the imdircacheserv take more than the time defined by the configuration key dirCacheUpdatePeriod to process a set of updates from the master. This could be due to a very large number of changes to the database in a short amount of time.

Effect: The event is of warning severity. There is no direct effect on service, but there could be secondary effects. If there was a large amount of new updates to the master oracle directory while updating the cache, then the next update may take even longer than the previous update, then the next update will take even longer, and so on. It is important to catch this early on as this problem has the potential to become more critical.

Action(s): Make sure the connection between the master Oracle Directory and imdircacheserv is working properly. Also make sure the configuration key dirCacheUpdatePeriod is not set too low.

Description: A mail filter has processed a message and bounced it (using the “bounce” action).

Parameters: filterName: the name of the filter executing.

message: the bounce message.

Cause: The “bounce” action the filter used.

Effect: This message is for informational purposes only.

Action(s): None required.



��,��.��$��

��,��'��

��,��

Description: A mail filter executed the “bounce” action twice, which the system does not allow. The system will honor only the first “bounce” action.


Cause: The mail filter may have a bug that is causing the multiple bounces.

Effect: This message is of warning severity.

Action(s): Fix the filter so that only one “bounce” can execute. It might be sufficient to put a “stop” action after one of the bounces.

Description: A mail filter executed two actions that conflict with each other. For example, you may not use the “toss”, “bounce”, and “reject” actions together, or with “sideline”, “keep”, or “forward”.


actionName: the name of the action that caused the conflict.

Cause: The mail filter may have a bug that is causing the conflicting actions to execute.

Effect: This message is of error severity.

Action(s): Fix the filter so that conflicting actions will not happen. It might be sufficient to put a “stop” action after one of the actions.

Description: A mail filter has processed a message and forwarded it to another address (using the “forward” action).


address: the forwardee’s address.

Cause: The filter used the “forward” action.



Log Events


��,��&�4��

��,��&�4��$��

Description: A mail filter has processed a message and caused the server to reject it (using the “reject” action). This will cause the message to return to the sender.


message: the rejection message.

Cause: The filter used the “reject” action.



Description: A mail filter executed the “reject” action twice, which the system does not allow. The system will honor only the first “reject” action.


Cause: The mail filter may have a bug that is causing the multiple rejects.


Action(s): Fix the filter so that only one “reject” can execute. It might be sufficient to put a “stop” action after one of the rejects.



��,��

��,��$��

��,��$��

Description: A mail filter has processed a message and sidelined it, so that an external program can examine it and either reintroduce or remove it.


dir: the sideline directory.

Cause: The filter used the “sideline” action.



Description: A mail filter executed the “sideline” action twice, which the system does not allow. It will only use the first “sideline” action.


Cause: The mail filter may have a bug that is causing the multiple sidelines.


Action(s): Fix the filter so that only one “sideline” can execute. It might be sufficient to put a “stop” action after one of the sidelines.

Description: A mail filter has processed a message and caused it to drop (using the “toss” action).


Cause: The filter used the “toss” action.


Action(s): None required, but you may want to make doubly sure that the filter is working properly. Since the “toss” action causes mail to be lost, take extreme care.

Log Events


��

File Input/Output Log Events

��.��*/��

Description: An error occurred when trying to parse a filter specification.

Parameters: lineNo: the line number where the parse error occurred.

linePos: the line position where the parse error occurred.

filterName: the name of the filter it is parsing.

Cause: The mail filter specification is illegal.

Effect: This message is of error severity.

Action(s): Correct the mistake in the filter specification. It makes sense to use the imfiltercheck utility to debug filters before installing them in a running system.

Description: There is a process blocked trying to write to a named pipe.

Parameters: namedPipe: the pathname of the named pipe.

Cause: InterMail processes create named pipes if the configuration key logNamedPipeMode is 1 or 2. If it is 2, then the process will block on the pipe if necessary until there is a process reading the pipe. If it blocks, it will write this entry to the logfile. Only use a logNamedPipeMode value of 2 in testing, and not in production, because if there is no reader or the reader exits, the process will block and perform no useful work.


Action(s): None, unless you do not want blocking; in which case, change the configuration key logNamedPipeMode.



��'��

��'��

Description: The call to close with file filename failed with system error systemErrString. This happens when trying to close a message file system file.

Parameters: filename: the name of the file.

systemErrString: the system error string.

Cause: • Signal caught during the call to close.

• Data not properly written out.


Action(s): Determine what caused this event.

Description: Copying the file srcfilename to the destination destfilename failed with status exitstat. Making a call to system does this.

Parameters: srcfilename: the name of source file.

destfilename: the name of the destination file.

exitstat: the exit status.

Cause: There could be several causes for this event.

• The permissions may not be right for the old file or for the destination or new file name.

• There may not be enough space on the device for the new file.

• The old file may no longer exist.

Effect: The event is of major severity. The occurrence of this event indicates that the machine that the server is running on is in a bad state. Memory probably exhausted.

Action(s): Check the permissions of the srcfilename and the destination directories. Check the quotas and size of the old file. Check the disk and memory usage on the host on which this server is running.

Log Events


��'��

��'��

Description: The creation of the file filename failed with system error systemErrString.



Cause: The file could be a message file, a lock file, a directory, or files for journaling. The system calls that could cause this event are open, mkdir, and access.

Effect: The event is of major severity. The occurrence of this event indicates that the machine that the server is running on is in a bad state. Memory probably exhausted.

Action(s): Verify disk space and memory not exhausted. Verify that the permissions for the directories and files are correct.

Description: The system call to open with filename filename failed with system error systemErrString.



Cause: • The file already exists.

• The listener process does not have adequate permissions to create the file.

• The system file table is full.


Action(s): Determine which of the causes are responsible for this event. If the file already exists, delete it and restart the server. If the permissions are not right, the process probably did not start correctly with the right user.



��)��

��

Description: The call to access with directory name dirName failed with system error systemErrString. This happens when the MTA is creating the spool subdirectories.

Parameters: dirName: the name of the directory.


Cause: • The process does not have adequate permissions to access the directory.

• The directory name is too long.

• A signal caught during the access function call.


Action(s): Check to make sure the process starts with the right user. Make sure that the directory name is the correct one for access. Verify that the permissions for the destination directory are correct.

Description: The call to fcntl() on file filename failed with error systemErrString. Specifically, there was a problem making the named pipe have non-blocking I/O.



Cause: The named pipe file had no readers. In order to avoid a block, called fcntl() to make the file have non-blocking I/O.

Effect: The event is of minor severity.

Action(s): NA.

Log Events


��

Description: Performing a file synchronization (fsync) on the file filename resulted in system error systemErrString. This acts on a message file.

Parameters: filename: the filename.


Cause: • System moved or removed file before the fsync call.

• A signal caught during the fsync call


However, if this event occurs frequently then upgrade the severity to major. This indicates that there is a problem with the message file space files.

Action(s): Using the information from systemErrString determine the cause for this event. The message file directories may need cleaning out and the MSS may need to restart.



��*��

Description: The attempt to link oldFilename to newFilename failed with error systemErrorString. This could happen when the system is in the process of bouncing, deferring, or forwarding mail and an error occurs. It also could occur when there are problems saving bad mail.

Parameters: oldFilename: the old file name.

newFilename: the new file name.

systemErrorString: the system error string.

Cause: Could be one or more of the following:

• The new file already exists.

• A signal caught during the link call.

• Too many symbolic links encountered.

• Existing or new file name is a null path name.

• The read/write permissions for the existing and/or new file do not allow the link.

Effect: The event is of minor severity if it occurs because the system is in the process of bouncing, deferring, or forwarding mail.

It is major if this event occurs frequently when bouncing, deferring, or forwarding mail.

If the error occurs because there is a problem saving bad mail, then this is of warning severity.

Action(s): Using the information from the systemErrorString, determine the cause of the error. Investigate the log for higher level operations to determine what actions to take.

Log Events


��*�)��

��*��

Description: The call to mkdir with filename dirName failed with error systemErrString. This happens when the MTA is attempting to create the error directory.

Parameters: dirName: the directory name.


Cause: • The user running this server does not have adequate permissions.

• The server did not start with the correct user.

• System resources exhausted.

• The filename is too long.

Effect: The event is of critical severity. The MTA will stop running when this event occurs.

Action(s): Using the information from systemErrString determine which of the causes are responsible for this event. Fix the problem and restart the MTA.

Description: An attempt to create a named pipe has failed. A system call to mknod did this.

Parameters: namedPipe: the name of the pipe.


Cause: • Memory exhausted.

• Bad filename or path.

• Signal caught while attempting to create the pipe file.

Effect: The event is of warning severity if the cause is a bad filename or signal caught.

It is critical if the cause is there is no memory left. This is an indication of more serious problems.

This event is minor on impact of service, but the impact on the system is critical in that there may be no pipe for this server.

Action(s): Using the filename and systemErrorString, determine the cause of this event.



��

��/��

��&��

Description: An attempt to memory-map a file failed.

Parameters: filename: the file name.


Cause: The system call to mmap(2) failed with the error given.

Effect: The effect on service is minor since it will not affect customers. The event is of critical severity in that journaling does not work.

Action(s): Verify that the permissions for the server and destination of journal files are correct. If these are right, contact your InterMail vendor.

Description: There was an attempt to write to a memory-mapped file but it was either not open or opened and then closed.

Parameters: filename: the name of the memory-mapped file.

Cause:

Effect: The event is of minor severity for the users and critical severity for the system is critical in that journaling does not work.


Description: Named pipe %s has no readers.

Parameters: namedPipePath: the full path of the named pipe.

Cause:

Effect:

Action(s):

Log Events


��/��)��

��/��

Description: The call to opendir with directory name dirName failed with system error systemErrString. This happens when trying to open the directory that holds the MTA control files.

Parameters: dirName: the name of the directory.


Cause: • Cannot access the directory.

• Memory exhausted.

Effect: The event is of warning severity for customers as it does not affect service, but the event is of critical severity for the system in that it is not possible to scan the control files.

Action(s): If it could not access the directory, it could be because the process did not start with the right user. Verify that the process logging this event has started with the correct user. Verify that the directory to open exists and has the appropriate permissions. If everything looks correct, restart the MTA. If the MTA still signals this event, contact your InterMail vendor.

Description: The call to open with file filename failed with system error systemErrorString. The opContext provides the context of the open call.


opContext: text explanation of attempted operation.


Cause: • The server performing the open does not have adequate permissions.

• The file does not exist.

• The server has too many open files.

• The system file is full.

Effect: The event is of major severity when it affects one of the servers.

Action(s): Using the information from systemErrorString determine the cause of the event.



��"��

��/��

Description: Could not use the named pipe because to do so requires ignoring the SIGPIPE signal and there is a non-default signal handler for that signal already installed.

Parameters: namedPipePath: the full path to the named pipe.

Cause:

Effect:


Description: An attempt to open a named pipe for writing failed. This happens when creating the logfile.



Cause: The permissions could be wrong for the directory. The process could have started with a user who does not have the appropriate permissions to create the named pipe.

Effect: The impact on service is minor. No customers are affected, but the impact on the system is critical in that there may be no pipe for this server.

Action(s): Check existence, ownership, and permissions of the directory. If the named pipe does exist, the program would have created it using mknod().

Log Events


��+��

��+��

Description: An attempt to write to a named pipe failed. This happens when writing to a logfile.



Cause: The named pipe may no longer exist, the named pipe have access permissions that deny the process to write to it.

Effect: The event is of warning severity. The effect on service is that this process is unable to write to its log file.

Action(s): Verify that the named pipe exists and has the appropriate permissions. Verify that the process has started with the correct user. If the system error string indicates that an exhausted resource, check the general health of this host and the disk usage.

Description: A write to the named pipe pipeName of line lineNumber only wrote numBytes. The error was systemErrorString. This happens when writing to a logfile.

Parameters: pipeName: the name of pipe.

lineNumber: the line number of the named pipe.

numBytes: the line number of bytes.


Cause: The named pipe may no longer exist, or the named pipe does not have permissions for the process to write to it.

Effect: The event if of warning severity.

The effect on service is that this process is unable to write to its log file.

Action(s): Verify that the named pipe exists and has the appropriate permissions. Verify that the process has started with the correct user. If the system error string indicates an exhausted resource, check the general health of this host and the disk usage.



�� /�

��&��

Description: The call to read resulted in end of file.

Parameters: None.

Cause: System error.

Effect: The severity of this event depends on the higher level operations this process is performing. The event is of warning to critical severity. Investigate the effect on service by looking at the log files for other events that are more specific to each process.

Action(s): This event alone has no context about operation being performed. Look at the log file for the process to determine the higher level operation and then follow the recovery procedure for that event.

Description: Performing a read resulted in system error systemErrorString. This is a low-level operating system type event.

Parameters: systemErrorString: the system error string.

Cause: • Physical I/O error occurred.

• Total amount of system memory available is insufficient.

Effect: The severity of this event depends on the higher level operations this process is performing. The event is of warning to critical severity. A hardware error may have occurred that would make this event have a severity of critical.

Action(s): Investigate the effect on service by looking at the log files for other events that are more specific to each process. Determine which cause is responsible for this event. Depending on the cause, perform the appropriate recovery action.

Log Events


��&��

��&��

Description: Renaming file oldFilename to newFilename failed with system error systemErrorString.

Parameters: oldFilename: the old filename.

newFilename: the new filename.


Cause: There could be several causes for this event. The permissions may not be right for the old file or for the destination or new file name. There may not be enough space on the device for the new file.

Effect: The event is of minor severity if one of the servers has signaled the error.

Action(s): Verify that the permissions are correct for the old file and the destination. Verify memory not exhausted. Verify the general health of the host machine.

Description: The system call to rmdir with filename dir failed with system error systemErrorString.

Parameters: dir: the name of the directory.


Cause: • The server performing the rmdir does not have adequate permissions.

• The name of the file is too long.


Action(s): Determine the cause responsible for this event. Expected directories may be missing.



��*��

��

Description: Performing an lseek results in the error systemErrorString.


Cause: System error.

Effect: The event is of major severity if the MSS, POP Server, or MTA signaled it. You must investigate the effect on service by looking at the log files for other events that are more specific to each process.

Action(s): Determine which cause is responsible for this event. Depending on the cause perform the appropriate recovery action.

Description: The {l,f,}stat command failed on file filename with systemErrorString. The context is either in the MSS or the Directory server.



Cause: • The server does not have adequate permissions.


• A signal caught during the stat call.

• The length of the filename is too long.

Effect: The event is of critical severity. The effect on service is that updating the DB database probably failed or that the MSS had a problem with the file containing the list of buckets.

Action(s): Using the information from systemErrString determine the cause of this event. If it looks like a problem updating the DB database, the Directory Server may have to restart. If this is a problem with the file containing the list of buckets, there are probably more severe problems with the MSS.

Log Events


��

��-��*��

Description: The statvfs command failed on file filename with systemErrorString. Currently, the only context where this message occurs is in the MSS. Matches FIOStatvfsErr.



Cause: • The server does not have adequate permissions.

• The file or directory does not exist.

• A signal is caught during the statvfs call.

• Too many symbolic links were encountered in the path.

• The length of a path component exceeds {NAME_MAX} characters, or the length of path exceeds {PATH_MAX} characters.

Effect: The event is of critical severity. The effect on service is probably that the MSS is having a problem with the file containing the list of buckets.

Action(s): Using the information from systemerrstring to determine the cause of this event. If this is a problem with the file containing the list of buckets, there are probably more severe problems with the MSS. If this appears to be a programming error, contact your InterMail vendor.

Description: The system call to unlink with file filename failed with system error systemErrorString.



Cause: • The server performing the unlink does not have adequate permissions.

• The name of the file is too long.

Effect: The event is of warning severity if the MTA signaled this event or this event relates to journaling. It is minor if the MSS signaled this event. Only adversely affects service if the MSS signaled this event. There will be small customer impact for this case.

Action(s): Determine which cause is responsible for this event. The expected files may be missing.



��+��

IMAP Log Events

��.��

Description: The call to write with file filename failed with system error systemErrorString. The opContext provides the context of the write.


Filename: text explanation of attempted operation.


Cause: • The server performing the write does not have adequate permissions.


• The server has too many open files.

• The system file is full.

Effect: The severity of this event depends on the higher level operations this process is performing.

The event is of major severity if the MSS, popserv, imdirserv, or the MTA signal this event.

Action(s): Investigate the effect on service by checking the log files. Look for other events that are more specific to each process.

Using the information from systemErrorString determine the cause of the event. If the server does not have adequate permissions, the server may not have started with the right user. If the system file is full or the file does not exist, check the general health of the host machine. If everything looks OK, investigate the log for information on higher level operations to determine whether a server must restart.

Description: One of the IMAP commands from the IMAP client specified a bad message number.

Parameters: msgNum: the message sequence number.

Cause: The IMAP client sent an IMAP command with a bad message number to the IMAP Server.

Effect: Not serious, this is a problem with the IMAP client.

Action(s):

Log Events


9��'��

��'��&��

Description: An error occurred while processing an IMAP command.

Parameters: None.

Cause: The error may be due to an internal problem with the IMAP Server or may result from a client error.

Effect: Usually has no significant effect. In some cases, a user may not be able to access his or her mail using the IMAP Server.

Action(s): Look in the IMAP Server log files for other log events relating to this client: there should be other log events with more specific information. Often no action is necessary because the error reflects a client mistake.

Description: An error occurred while processing an IMAP command.

Parameters: explanation: explanation of the error. This is the same explanation sent to the client in the command response.

Cause: The error may be due to an internal problem with the IMAP server or may result from a client error. The explanation indicates the cause.

Effect: Depends on the explanation parameter: usually has no significant effect. In some cases, a user may not be able to access his or her mail using the IMAP server.

Action(s): Depends on the explanation parameter. Often no action is necessary because the error reflects a client mistake.



��'��.��*��

��'��

��'��$��/��

Description: Connection broken between the IMAP Server and the IMAP client that is running on host host.

Parameters: host: the host the IMAP client is running on.

Cause: • The IMAP client could have broken the connection intentionally or unintentionally.

• The host machine host could be in a strange state or could have rebooted.

Effect:

Action(s): None.

Description: The IMAP server successfully validated the user.

Parameters: None.

Cause: The IMAP server is successfully validating the user.

Effect: This is a notification.

Action(s): None.

Description: Connection with the IMAP client has terminated because the connection was idle for too long.

Parameters: None.

Cause: The user's connection was idle.


Action(s): None.

Log Events


��)��

��

��!��

Description: Connection with the IMAP client has terminated.

Parameters: None.

Cause: The user’s connection has terminated.


Action(s): None.

Description: The MSS reported an error and the IMAP Server was unable to continue the current operation. It disconnected the client.

Parameters: None.

Cause: The MSS reported an error to the IMAP Server. There may be a problem with the user’s mailbox.

Effect: Client disconnected.

Action(s): Check the MSS log files for problems occurring at about the same time.

Description: The IMAP Server has hit the maximum number of connections configured by the system administrator, and will not accept additional connections until other clients disconnect.

Parameters: count: the maximum number of connections.

Cause: There are too many incoming connections.

Effect: The server does not allow clients to login.

Action(s): If these messages persist, consider raising the connection limit, or add additional servers to an overloaded server.



��!��

��

��

Description: The IMAP server does not support proxy mode. Accounts that are in proxy mode are not accessible using the IMAP server.

Parameters: None.

Cause: An IMAP client is trying to log into an account that is in proxy mode.

Effect: This is an informational message.

Action(s): None.

Description: The IMAP client sent an invalid command that the IMAP Server could not understand.

Parameters: explanation: explanation of the protocol error. This is the same explanation sent to the client in the error response.

Cause: The IMAP client sent an invalid command.

Effect: This is an informational message only.

Action(s): None.

Description: Synchronization error with Message Store Server: got “reply” reply in state “state”.

Parameters: reply: name of the unexpected reply received.

state: state of the IMAP connection when it received the reply.

Cause: The Message Store Server could be in a strange state. The IMAP Server could be in a strange state.

Effect: May indicate a problem with the MSS or the IMAP Server. Clients may not be able to access mail with IMAP.

Action(s):

Log Events


��-�)/��/�/��

��$��

Description: This event occurs when a MSS notifies the IMAP Server that a new message has arrived with a UID lower than that of the last message in the mailbox.

Parameters: newuid: the UID of the newly arrived message.

olduid: the UID of the last message in the mailbox.

Cause: A MSS is notifying the IMAP server of new message arrivals in the wrong order.

Effect: IMAP clients expect messages in a mailbox to have strictly increasing UIDs. Some IMAP client software may become confused if messages are in the wrong order.

Action(s): None needed. Closing and reopening the mailbox from within the IMAP client will sort the messages correctly.

Description: The keyword string %s was too long to be stored in the database; the maximum length is %d.

Parameters: The list of keywords being set and the maximum allowed size of a keyword list as specified by the maxKeywordLength configuration key.

Cause: The user (client) tried to store keywords with a total length greater than the maximum specified by the maxKeywordLength configuration key. The space required by the keywords is the sum of the lengths of each of the keywords added plus 1 byte per keyword for overhead.

Effect: The keywords will not be stored for the message. This occurs as a result of an IMAP STORE command.

Action(s): Increase maxKeywordLength configuration key.

Note: This can increase the storage requirements of the MSS.



LDAP Log Events

��B9��9 ��B9��9��9��9:��;9

��B9��9 ��B9��9��9��9C��9 ��C9��9

��B9��9 ��B9��9��9��9C��9 ��C9��9

Description: A line in the configuration file is incorrect and cannot be parsed.

Parameters: <string> = name of the configuration file.

<integer> = line number in the file where there is an error.

Cause: Something is wrong with a line in the configuration file, to the extent that it cannot be understood.

Effect: Line is ignored.

Action(s): Fix the line, if it is important.

Description: The replogfile directive is missing a distinguished name.



Cause: See description.

Effect: The server exits.

Action(s): Fix the directive in the configuration file.

Description: The rootdn directive is missing a distinguished name.






Log Events


��B9��9 ��B9��9��9��9C��!9 ��C9��9

��B9��9 ��B9��9��9��9C��9 ��C9��

��B9��9 ��B9��9��9��9C��9 ��C9��9

Description: The updatedn directive is missing a distinguished name.






Description: The suffix directive is missing a distinguished name.






Description: An include directive is missing the expected filename.








��B9��9 ��B9��9��9��9C��9 ��C9��9

��B9��9 ��B9��9(��9��9C��9 (��>B��?�C9��9

��B9��9 ��B9��9(��9��9C��C9��9:��;

Description: A srvtab directive is missing the expected filename.






Description: The replica directive is missing the host name.






Description: The replica directive is missing a host name.




Effect: The directive is ignored.


Log Events


��B9��9 ��B9��9��9��9C��0��9 ��C9��9

��B9��9 ��B9��9��9��9C��9 ��C9��

Description: The sizelimit directive in the configuration file is missing the actual limit.






Description: The timeline directive in the configuration file is missing the actual limit.








��B9��9 ��B9��9��9��9C��9 ��D9 ��!�C9

��B9��9 ��B9��9��E��9��9C��9 ��E��C9��9

Description: Attribute decoding is missing a name.

Parameters: <string> = name of the input file.


Cause: Attribute is missing name as shown.

Effect: The attribute is ignored.

Action(s): Find and fix the attribute at the source.

Description: The lastmod directive is missing the on/off parameter.






Log Events


��B9��9 ��B9��9��E��9��9C��9 ��E��C9��9

��B9��9 ��B9��9��9��9C��9 ��C9��9

��B9��9 ��B9��9��9��9C��9 ��C9��9

Description: The readonly directive is missing the on/off parameter.






Description: The rootpw directive is missing a password.






Description: The configuration line that specifies the database type, is missing the type.





Action(s): Fix the configuration line for database type to read correctly.



��B9��9 ��B9��9-&�9��9C��9 -&��C9��9

��B9��9 ��B9��9��9��9��9��9�9��9��9:��;9

��B9��9 ��B9��9��9��9��9��9�9��9��9:��;

Description: The referenceURL directive is missing the URL.






Description: The readonly directive must appear inside a database definition.






Description: The replica directive must appear inside a database definition.






Log Events


��B9��9 ��B9��9��9��9��9��9�9��9��9:��;9

��B9��9 ��B9��9��9��9��9��9�9��9��9:��;9

��B9��9 ��B9��!9��9��9��9��9�9��9��9:��;9

Description: The rootdn directive must appear inside a database definition.






Description: The rootpw directive must appear inside a database definition.






Description: A suffix directive must appear inside a database definition.








��B9��9 ��B9��*��9��9C ��C9��9��9��9:��;9

��B9��9 ��B9��9��9��9��9��9�9��9��9:��;9

Description: A directive given outside a database definition is not recognized.






Description: The updatedn directive must appear inside a database definition.






Log Events


��@�B9��9 ��B9�!��9��9��9 ��9��9C��!9 ��A�C9��9:��;9

��@�B9��9 ��B9��*��9��9C ��A�C9��9��9��9:��;

Description: The distinguished name in the suffix directive is followed by unnecessary text.

Parameters: <string1> = name of the configuration file.


<string2> = unnecessary text.




Description: A directive given inside a database definition is not recognized.

Parameters: <string1> = name of the configuration file.


<string2> = unrecognized directive.






��@�B9��9 ��B9��*��9��!9C ��A�C9��9��9��9:��;9

��9��9��9��9:;

Description: Attribute syntax is unknown.

Parameters: <string1> = name of the input file.

<integer> = line number in that file.

<string2> = text that is not understood.

Cause: Syntax error in attribute line shown.



Description: Basic Encoding Rules decoding is failing due to lack of memory.

Parameters: None.

Cause: Request to connect is malforming BER encoding, or machine is out of resources.

Effect: Processing of the connection stops, and server is likely to exit soon since memory allocation is failing.

Action(s): Find out what is using up memory, or if normal operations, get more memory or increase swap on the machine.

Log Events


��9��9��9��9:@;

��9��9��9��9:A;

��9��9F! (�!�9

Description: Basic Encoding Rules decoding is failing to allocate resources.

Parameters: None.




Description: Basic Encoding Rules decoding is failing to allocate resources.

Parameters: None.




Description: Basic Encoding Rules decoding is failing on the input data.

Parameters: <hex> = hex representation of the value that is returned from ber_get_int.

Cause: Request to connect is malforming BER encoding.

Effect: The connection is closed without any returned data.

Action(s): Fix the client that is sending incorrectly formatted data.



��*��9��9F! (�!�9

��9��9��9��A:;

��9��9��9��(��:@;


Parameters: <hex> = hex representation of the value that is returned from ber_get_int.

Cause: Request to connect is malforming BER encoding.

Effect: The connection is closed without any returned data.


Description: Basic Encoding Rules output is failing for the given data.

Parameters: None.

Cause: Result cannot properly form a BER encoded value.

Effect: LDAP Operation Error is returned to client: ber_printf value.

Action(s): Find and fix the data causing the failure to encode.


Parameters: None.




Log Events


��9��9��9��(��:A;

��9��9��9��(��:6;

��9��9��9��(��:5;


Parameters: None.





Parameters: None.





Parameters: None.






��9��9��9��(��:G;

��9��9��9��9:;

��9��9��9��9:;


Parameters: None.





Parameters: None.

Cause: Request to abandon does not have an id number or is malforming BER encoding.

Effect: Request is ignored.

Action(s): Find and fix the encoding of the request.


Parameters: None.

Cause: Request to add is malforming BER encoding.

Effect: Request is ignored, decoding error is returned to client.

Action(s): Find and fix the incorrect encoding of the request.

Log Events


��9��9��9��9:;

��9��9��9��9:;

��9��9��9��9:;


Parameters: None.

Cause: Request to bind is malforming BER encoding.

Effect: Request to bind is not performed, Protocol Error is returned to client.

Action(s): Fix the connecting client to send correct protocol.


Parameters: None.

Cause: Request to compare is malforming BER encoding.

Effect: Request is dropped, Protocol Error is returned to client.

Action(s): Fix the client to send properly formed request.


Parameters: None.

Cause: Request to delete is malforming BER encoding.

Effect: LDAP Protocol Error is returned to client.




��9��9��9��9:;

��9��9��9��9:;

��9��9 ��@�9��9��9 ��A�9��9��9


Parameters: None.

Cause: Request to modify is malforming BER encoding.

Effect: Request is ignored, LDAP Protocol Error is returned to client.

Action(s): Fix the client that is sending malformed requests.


Parameters: None.

Cause: Request to modify relative distinguished name is malforming BER encoding.

Effect: Request is ignored, LDAP Protocol Error is returned to client.

Action(s): Fix the client that is sending malformed requests.

Description: The LDAP server is unable to allocate memory.

Parameters: <integer1> = number of elements in attempted allocation.

<integer2> = number of bytes per element in attempted allocation.

Cause: Request for memory is failing, possibly the machine is out of swap.



Log Events


��9��9��9��*��9C ��C9

��9��9��9��9��9C ��C9

��9��9��9��9��9C ��C929��9��(H9

Description: Cannot open the file while attempting to acquire a lock file.

Parameters: <string> = lock file.

Cause: File permissions or other disk problems.

Effect: The lock is not acquired; other parts of the server can fail.

Action(s): Determine the problem with the referenced file.

Description: Unable to open the specified file after obtaining a lock.

Parameters: <string> = file attempting to open after acquiring a lock for it.

Cause: File permissions or other disk problems.

Effect: The lock is released, but the specified file is not open; other parts of the server can fail.

Action(s): Determine the problem with the referenced file.

Description: The configuration file cannot open.


Cause: File specified does not exist or permissions are not set correctly.

Effect: The LDAP server exits.

Action(s): Fix the specification of the file, or file permissions appropriately.



��0�929��*��9��9 ��9

��9: ��@�;<9��9: ��A�;9��9��9

��9: ��@�;<9��7��9��9: ��A�;9��

Description: Normalization of the distinguished name is failing with an unknown state.

Parameters: <integer> = decimal state that is found and not recognized.

Cause: The distinguished name given is malformed.

Effect: Normalization stops, distinguished name is returned as-is, can have consequences for further processing.

Action(s): Find the source of the malformed distinguished name and fix it.

Description: Schema analysis is finding an entry (shown) which has an attribute (shown) that is not allowed.

Parameters: <string1> = incorrect entry.

<string2> = attribute that is not allowed.

Cause: Provided entry does not match the schema.

Effect: Entry cannot be processed.

Action(s): Fix the schema, or correct the data.

Description: Schema analysis is finding an entry (shown) which is missing a required attribute as given.

Parameters: <string1> = incorrect entry.

<string2> = attribute that is not allowed.


Effect: The entry cannot be processed.


Log Events


��9��9

��9��9 ��9��9��9

�9��4��9��9��9��9: ��;9


Parameters: None.

Cause: An attribute-value assertion (ava) is malforming BER encoding.

Effect: The LDAP Protocol Error response is returned to the client.

Action(s): Fix the encoding provided to the server for the ava.


Parameters: <integer> = number of bytes attempted to allocate.




Description: Schema analysis is finding an entry (shown) which does not have an object class defined.

Parameters: <string> = entry for which an object class is not found.


Effect: The entry cannot be processed.




��9��9��9��9 ��9

��B9��I�9��9��9 ��9

��9��!��9��9C��C<9C��C<9C��C<9C��C<9��9C��C9

Description: An add request cannot find the values for the given type.

Parameters: <string> = value of the type field.

Cause: Request to add does not have a value for type shown.

Effect: The request is ignored, protocol error is returned to client.

Action(s): Find and fix the request at the source.

Description: An internal server request to delete a pending operation is failing to find that operation.

Parameters: <integer> = integer tag for the operation to be deleted.

Cause: Internal server error.

Effect: The requested deletion is not performed.

Action(s): None possible.

Description: Attribute syntax is unknown.

Parameters: None.

Cause: Syntax error in attribute line shown.



Log Events


��9��9 ��9��9��9

��A��B9��9 ��9(��9��9��9C ��@�C9��9C ��A�C9:��9��;

��A��B9��9 ��9(��9��9��9


Parameters: <integer> = number of bytes attempted to allocate.




Description: A single entry has multiple distinguished names. The first is used, the rest ignored.

Parameters: <integer> = number of the entry at fault.

<string1> = first distinguished name that is found (used).

<string2> = second distinguished name that is found (ignored).


Effect: See description.


Description: The entry has no distinguished name.

Parameters: <integer> = number of the entry at fault.

Cause: Malformed data.

Effect: The entry is ignored.

Action(s): Fix the data as required.



��A��9: ��;9�!��9C& �-�$C9

��A��9: ��;9��*��9

��9��9 ��9

Description: When attempting to encode a server answer, the expected format cannot be found.

Parameters: <string> = string that is expecting RESULT but is not getting it.


Effect: The encoding of the result stops.


Description: When attempting to encode a server answer, the expected format cannot be found.

Parameters: <string> = string which is not recognized as a valid format.


Effect: The encoding of the result stops.



Parameters: <string> = string that is attempting to be duplicated.


Effect: Server exits.


Log Events


$��9��9��*��9:��!9 ��;9

��*��9��9��9 ��9��9��

��*��9��9��9 ��9��9��

Description: More than the maximum allowed number of tokens is given in the configuration file.

Parameters: <integer> = maximum number of tokens that are allowed.

Cause: Improper configuration.



Description: A filter is specified with an unknown type.

Parameters: <integer> = type number of the filter at fault.


Effect: An LDAP Protocol Error is signaled.

Action(s): Fix the filter specification.

Description: When freeing a filter, the type is not recognized.


Cause: Invalid filter type in list of filters; this should not occur.

Effect: The filter is skipped and a message is logged.

Action(s): Turn on filter tracing and determine the source of the invalid filter.



��*��9��9��9 ��9��9��:;9

��*��9��9 ��9

��96JF9��9

Description: A filter that is running against a query does not have a recognized type.


Cause: Invalid filter specified.

Effect: The filter is skipped, no match is found.

Action(s): Determine the filter at fault and eliminate.

Description: The version in the bind request is not recognized.

Parameters: <integer> = unrecognized version.


Effect: Server returns Protocol Error, declines bind from client.

Action(s): Fix the client to use a compatible protocol to the server.

Description: Standard message when the bind request in V3.0 form is recognized.

Parameters: None.

Cause: Version 3.0 has special encoding rules to watch for when binding.

Effect: Handled by server.


Log Events


Message Store Log Events

��,�� !��

��,��*��

Description: While attempting to create a message store, a message store with name msName already existed.

Parameters: msName: the message store name.

Cause: This is likely to happen when creating message stores. When creating message stores on demand, another thread may have created the message store first.

Effect: This message is of informational severity.

Action(s): Verify that the message store msName exists.

Description: A message store could not open because it is POP locked in exclusive mode.

Parameters: None.

Cause: A POP session on the message store was already active at the time, or the message store briefly locked for a maintenance activity.

Effect: The message store is not accessible until unlocked.

Action(s): No action is necessary. This condition occurs during the course of normal operation because of the POP3 specification requiring exclusive locks on message stores. This notification not normally logged.



��.��.��

��.��)��

��.��

Description: There is not enough information passed to the internal code for the MSS to generate a bounce notification.

Parameters: None.

Cause: The code that passes invalid information to the function for delivering a bounce notification causes this internal error.

Effect: This really should not happen very often. An internal error is of major severity. Affects all the message stores: missing bounce notifications.


Description: The database name dbName provided when starting up the MSS is not valid.

Parameters: dbName: the database name.

Cause: The script to start the MSS is incorrect.

Effect: The event is of critical severity. No access to any message stores served by this database.

Action(s): Verify that the message store server starting correctly with the right arguments.

Description: A message store of an unknown type identified user user. This event should never occur with database message stores.

Parameters: user: the user name for the mail account.

Cause: A client program and an entry in the Integrated Services Directory specified an invalid message store.

Effect: The event is of minor severity. Affects a single message store only: no access.

Action(s): Check the Integrated Services Directory to verify that the user points to a valid message store.

Log Events


��.��

��.��#��

��.��

Description: Invalid statistic encountered when fetching statistics about a message store server.

Parameters: None.

Cause: A client program specified an invalid statistic, likely a statistic meant to apply to message stores only (rather than to the message store server).

Effect: The event is of minor severity. Affects a single message store only.


Description: The message store server received a query with an invalid type.

Parameters: None.

Cause:



Description: Invalid statistic encountered when fetching statistics about a message store msName.

Parameters: msName: the name of the message store.

Cause: A client program specified an invalid statistic.





��.��-&�

��.��

Description: Type of message store not recognized when accessing a message store for mailbox mailboxname. This event is unlikely to happen with database message stores.

Parameters: mailboxname: the mailbox name.

Cause: A client program and an entry in the Integrated Services Directory specified an invalid message store.

Effect: This message is of minor severity. It affects a single message store only: no access.

Action(s): Using the mailboxname, check the Integrated Services Directory to verify that the user points to a valid message store.

Description: The message broadcast failed because message store msName among numberms was not available for more than two hours.


numberms: the number of message store.

Cause: Message store msName may be in use by another Message Store Server.

Effect: The event is of minor severity. Affected message stores will not receive the broadcast message.

Action(s): Verify the state of message store msName.

Log Events


��.��*��($��

��'��)��

Description: A particular message is too long to fit into a particular message data area bucket.

Parameters: Bucket Path Length: the maximum allowed length of a bucket path (relative to $mssBlobDir).

Bucket Path: the bucket path (relative to $mssBlobDir) is longer than allowed.

Message Size: the length of a bucket directory (relative to $mssBlobDir) is longer than allowed.

Cause: • The message file system is running low on disk space.

• Some damage is occurring to the message data area file system.

• This particular bucket is becoming over-loaded.


Action(s): If this message is generated only a few times, take no action. To stop these warnings, remove this directory from the buckets file, however, it is possible that the directory will be added to the buckets file the next time that imbucketscreate is run.

If this message is generated many times and disk space is confirmed low, add more disk space to the message file system. If disk space does not seem to be a problem, add more directories to the same message data area file system. If error continues, contact your InterMail vendor.

Description: The message store server has detected an internal inconsistency in message store msName. This has been determined after either finding a loaded message store, loading an existing message store or creating a new message store.


Cause: System or hardware.

Effect: The event is of major to critical severity. If the event is repeating for multiple message stores, it may affect all message store access for this machine.

Action(s): Check for database errors. Verify database validity (if error repeats). Check for system errors. Restart the message store servers. Restart the database. Restart system.



��)��

��)��

��)��

Description: The attempt to delete the message store failed because it is in use.

Parameters: None.

Cause: The administrator is attempting to delete a message store that is currently in use. They will not be able to delete the message store.

Effect: The event is of minor severity. Affects a single message store only: will not delete the message store.

Action(s): Check for the correct message store, especially if using a generated list. If the message store is correct, wait until the message store closes before deleting it.

Description: The attempt to deliver the message store failed because the destination folder did not exist.

Parameters: None.

Cause: • The folder did not exist.

• The mailbox’s quote might be full.

• System resources might not be available.

Effect: The event is of minor severity. Affects a single message store only: the message will be delivered to the inbox folder.

Action(s): None.

Description: An attempt to create a folder folderName but the folder folderName already exists.

Parameters: folderName: the name of the folder.

Cause: A client of the message store server tried to create a folder with the same name as one that already exists.


Action(s): This is likely a user error, so there is no action required. If the error is only with POP clients, contact your InterMail vendor.

Log Events


��

�� .��*��

Description: Message store determined to be empty.

Parameters: None.

Cause: A message store has no messages in its InBox.

Effect: The processing of an empty message store speeded up.

Action(s): No action is necessary. This condition occurs during the course of normal operation when the system optimizes the processing of an empty message store. It does not normally log this notification.

Description: No valid bucket directories are found in the buckets file.

Parameters: None.

Cause: • The buckets.dir file contained invalid top level directory or directories when imbucketscreate was last run.


• The buckets file itself is being edited incorrectly.

• The buckets file is empty.

Effect: This critical error prevents the MSS from accepting messages. Until the problem is fixed, mail is deferred. The MSS still provides the POP server with previously stored messages.

Action(s): Inspect the $mssBlobDir/buckets file. Confirm whether the directories listed therein are valid.

If there is a problem with the message file system, make the appropriate repairs.

If there is a problem with the listing in the buckets file, then inspect the $mssBlobDir/buckets.dir file and confirm that it contains a valid top level directory or directories.

If the buckets.dir file is incorrect, then change it to contain a single line which lists the top level directory of your message file area, relative to $mssBlobDir.

If there appears to be nothing wrong with the buckets.dir file, then copy aside the incorrect buckets file (to show your InterMail vendor), then run $INTERMAIL/lib/imbucketscreate. If error continues, contact your InterMail vendor.



��

��

��

Description: Older servers cannot empty any folder other than the Trash folder.

Parameters: None.

Cause: This event could only occur with different versions of InterMail servers and the InterMail message store.

Effect: The event is of minor severity. Message stores served by the server cannot empty folders other than Trash.

Action(s): The message store server is an old version and needs updating. Check revisions of InterMail software. Upgrade the software or re-install as required. pkginfo -l InterMail tells you the version number of the installed package on any host.

Description: Attempt to create a message store using an empty name.

Parameters: None.

Cause: Mailbox for a user specified incorrectly in the Integrated Services Directory.

Effect: The event is of minor severity. Affects an individual user only: message store not properly identified.

Action(s): Verify that the mailbox names for the mail accounts to create are valid.

Description: Folder folderName1 cannot contain folder folderName2 because folderName2 already contains folderName1.

Parameters: folderName1: the name of the containee folder.

folderName2: the name of the container folder.

Cause: A client of the message store server requested an improper move of a folder.

Effect: This message is of informational severity. Affects a single message store only.

Action(s): None. This is a user error.

Log Events


��

��

Description: The folder folderName2 is no longer in folder folderName1.

Parameters: folderName1: the name of the container folder.

folderName2: the name of the containee folder.

Cause: Happens when message store server is to move a folder to a new container folder, or if a rename of a subfolder occurs. Multiple clients are accessing a message store by either performing folder actions simultaneously (such as a shared message store) or a client has not updated the result of a previous folder action and has out of date information.



Description: A client of the message store server attempted to move folder folderName, which is not movable. This folder is probably the trash folder.


Cause: An attempt to move either the trash folder or any other folder by a client of the message store server.





��&��

��&��

Description: A client of the message store server attempted to remove folder folderName which cannot be removed. This folder is probably the trash folder.

Parameters: folderName: The name of the folder

Cause: An attempt to remove the trash folder by a client of the message store server.


Action(s): This is a user error.

Description: A client of the message store server attempted to rename folder folderName, and this folder cannot have another name. This folder is probably the trash folder.


Cause: An attempt to rename either the trash folder or any other folder by a client of the message store server.



Log Events


��.��*��

��

Description: A particular message is too big to fit into a specific message data area bucket.

Parameters: Bucket Path: the path (relative to $mssBlobDir) of the bucket which is running out of room.

Message Size: the size of the message that does not fit into the bucket.

Cause: • The message file system is running low on disk space.


• This particular bucket is over-loaded.

Effect: The event is of critical severity. If this warning is generated seldom, then only a few buckets are full and there is a negligible effect on service. However, if this warning is generated for many buckets, it is likely that the message data area is running low on disk space, or else that some other disk problem is occurring to the message data area, which should be addressed as soon as possible.

Action(s): • If this message is generated only a few times, no action needs to be taken.

• To stop these warnings from being generated, remove this directory from the buckets file. It is possible that the directory will be added to the buckets file the next time that imbucketscreate is run.

• If this message is generated many times, and it is confirmed that disk space is low, then add more disk space to the message file system.

• If disk space does not seem to be a problem, add more directories to the same message data area file system.

• If error continues, contact your InterMail vendor.

Description: The mss constructor failed to initialize successfully.

Parameters: None.

Cause: See previous Error level messages in the MSS log file.

Effect: The event is of major severity. Affects a single message store only: no access.

Action(s): Check the MSS logs for an immediately preceding error level log entry, correct the problem, and restart the MSS.



��

��/�4&��

��$��

Description: The message store server received a query for invalid message flags.

Parameters: None.

Cause:


Action(s): If the error repeats frequently, contact your InterMail vendor.

Description: An internal id does not refer to an object.

Parameters: None.

Cause:

Effect: The event is of major (possibly critical) severity. The effect on service depends on the object that caused the alarm. This alarm usually affects a single user. However, if it floods, it could affect the entire MSS process.

Action(s): Reboot the server taking the error if the alarm is repeating several times a minute. If problem does not clear up, contact your InterMail vendor.

Description: An attempt is being made o store a keyword string which is longer than the space allowed.

Parameters: keywordstring: The keyword string which is being attempted.

maxkeywordlength: The maximum number of bytes allowed for the keyword string.

Cause: The IMAP server, c-api, or perl-api is trying to store keywords.

Effect: The keywords for that message will not be modified

Action(s): Shorten the keyword string length to be less than or equal to that of the maxkeywordlength

Log Events


��0�

��

Description: The size of the message msgSize exceeded the maximum allowed per message for message store msName. It will not create the message.

Parameters: msgSize: the size of the message in bytes.

msName: the message store name.

Cause: The configuration of message store msName does not allow creating messages larger than a maximum size.

Effect: The event is of warning severity. Affects individual message store only: cannot deliver mail to this message store unless the number of messages decreases or the limit increases.

Action(s): Verify that the configuration of message store msName is correct. Request that customers download their mail.

Description: The number of messages in message store msName is at limit maxNumMsgs. It did not create the new message.


maxNumMsgs: the maximum number of messages allowed for this message store.

Cause: The configuration of the message store msName allows a maximum of maxNumMsgs.

Effect: The event is of warning severity. Affects an individual message store only: no more mail delivered to this message store until the number of messages decreases or the limit is increases.

Action(s): Verify that the configuration of message store msName is correct. Request that customers download their mail.



��$��0�

��./�(��

Description: The size of the message store msName is near enough to the quota for maximum size (maxsize), such that it cannot create the message because this would exceed the quota.


currentsize: the current number of bytes stored for this message store.

msgsize: the size of the message in bytes.

maxsize: the maximum number of bytes for this message store.

Cause: The configuration of message store msName allows a maximum of maxsize bytes stored.

Effect: The event is of warning severity. Affects individual message store only: no more mail delivered to this message store until the size of the message store decreases (or the limit increases).

Action(s): Verify that the configuration of the message store msName is correct. Request customers to download their mail.

Description: When attempting to access the message store for the specified user, another MSS had loaded it on the given port number. See Shared Memory Table.

Parameters: portNumber: the port number the other MSS is listening on.

Cause: One MSS opened a message store when another MSS attempted to open it.


Action(s): None. This is expected behavior.

Log Events


��!'��

��)��

��/�4��

Description: Attempt to deliver mail to or read mail from a mailbox mailboxname, which the system has authorized, but not yet created. The system created this mailbox on the fly.

Parameters: mailboxname: the name of the mailbox created.

Cause: The system created this mailbox on the fly and this log entry notes that. It is not an error event.



Description: No database name specified when starting the message store server.

Parameters: None.

Cause: The script to start the MSS may not be correct.

Effect: The event is of critical severity. Cannot access any message stores on the machine this database serves.

Action(s): Verify that the message store server is starting correctly with the right arguments.

Description: The object objectType does not exist. The last RME operation on the message store server was rmeOp.

Parameters: objectType: the object type.

rmeOp: the RME operation.

Cause: This is a programming or system error.

Effect: This message is of major severity. The effect on service depends on the circumstances that lead to the alarm.

Action(s): If the error is repeating more than once every few minutes, restart the server reporting the error. Check for system errors. If the error continues, contact your InterMail vendor.



��.��

��'��

��)��

Description: Message msgId in message store msName in folder folderName is in an obsolete format. The message store is not able to complete the request to fetch a range of text from the message body. This event may occur after upgrading from an earlier version of InterMail.

Parameters: msgId: the message id.

msName: the name of the message store.

folderName: the name of the folder.

Cause: Message stored in the message store in an obsolete format, perhaps by an older installation of InterMail.

Effect: The event is of minor severity. It affects a single message only: no access.

Action(s):

Description: A message with message id msgId added to message store msName.



Cause: This is not an exception or error. It is strictly a notification.


Action(s):

Description: A message with message id msgId deleted from message store msName.



Cause: This is not an exception or error. It is strictly a notification.



Log Events


��)��

��*��

��

Description: A client of the message store server attempted to retrieve a message with message id msgId. This ID not found.


Cause: While doing account creation or broadcast, there was no welcome message or broadcast message or gave an incorrect message id.

Effect: The event is of minor severity. Affects an individual message store.

Action(s): • Check for the welcome message in the sysadmin account.

• Check the welcome message ID in the Directory Server.

• Check for the broadcast message.

Description: Message msgId currently locked.


Cause: A client has locked a message that something else is trying to reference.

Effect: The event is of informational severity. It affects an individual message store.

Action(s): None. User should retry operation later.

Description: The message msgId is no longer in folder folderName.



Cause: Another client may have moved or deleted the message in question, or this client did not update its state correctly for a previous operation.

Effect: The event is of warning severity. It affects an individual message store only

Action(s): Probably none. If the error repeats, this may be an indication of other more serious error with the folder folderName. Look in the log file for the MSS for other more serious events.



��*��

��&��&��

Description: The message msgId to unlock is not locked. (This functionality is becoming obsolete.)


Cause: Message already unlocked. Operation probably repeated.

Effect: The event is of informational severity. Affects a single message store only.

Action(s): None.

Description: Read length bytes starting at byte offset from message id msgId in message store msName in folder folderName by user userName.

Parameters: length: the number of bytes read.

offset: offset of the first byte read.

msgId: the message id.



userName: the name of the user who read the message.

Cause: Expected behavior.

Effect: None. The event is of informational severity.

Action(s): None, this is a notification of expected behavior.

Log Events


��&��

��,��)��

Description: Read a message with message id msgId in message store msName in folder folderName by user userName.




userName: the name of the user who read the message.

Cause: This is expected behavior.



Description: The message store is not currently allowing delivery of new messages: no new messages will be stored in the message store.

Parameters: None.

Cause: The configuration of the message store does not allow delivery of new messages.

Effect: The event is of warning severity. It affects an individual message store only: cannot receive mail.

Action(s): Verify that this is the correct configuration for the message store.



��&��(�

��-��*��

��+��

Description: The user userName does not have permission to perform the requested operation on the message store.

Parameters: userName: the user name.

Cause: The process that requested the operation is not running as the correct user, or a process running under an incorrect user name created a message store.

Effect: The event is of minor (possibly major) severity. Affects a single message store only: user may not be able to fetch mail.

Action(s): Verify that each of the servers is running as the correct user: check configuration data and restart servers as necessary.

Description: All messages in folder folderName currently locked. (This functionality is becoming obsolete.)


Cause: User error.

Effect: The event is of minor severity. It affects a single message store only.

Action(s): None.

Description: Welcome message (message id msgId) not found, when attempting to add it to a newly created message store for mailbox mailboxname.

Parameters: msgId: the message id for the welcome message.

mailboxname: the name of the mailbox.

Cause: Welcome message inadvertently deleted from the sysadmin account or the welcome message ID is incorrect in the configuration database.

Effect: The event is of minor severity. It affects individual newly created message stores.

Action(s): Check for the welcome message in the sysadmin account.

Check the welcome message ID in the configuration database.

Log Events


��,��&��

��,��&��

��,��(&��

Description: The folder folderName already deleted.

Parameters: folderName: the name of the folder

Cause: Subfolder in a search folder already deleted.

Effect: The event is of warning severity. It affects a single message store only.


Description: The message msgId already deleted.


Cause: Message in a search folder already deleted.



Description: The search container searchContainer already deleted.

Parameters: searchContainer: the search container.

Cause: Search folder already deleted.





��

��

��/�4��*��

Description: When attempting to retrieve the specified message store for mailbox mailbox, there was no message store.

Parameters: mailbox: the mailbox name.

Cause: An entry in the Integrated Services Directory is incorrect.

Effect: The event is of minor severity. It affects a single message store only: no access to this message store allowed.

Action(s): • Verify that the ISD is up-to-date.

• Check and correct the entry for mailbox in the Integrated Services Directory.

• Verify that on-the-fly account creation is turned on when expected.

Description: A client requested an operation of the message store server with a null or empty string folder name.

Parameters: None.

Cause: This is probably a client error.


Action(s): Check InterMail and system logs for other serious errors. If error repeats frequently, reboot InterMail servers. If error continues, contact your InterMail vendor.

Description: User userName on machine host is currently viewing a message or folder while another client was attempting to move, remove, or replace it.


host: the name of the machine the user is on.

Cause: Multiple clients are viewing a message store.


Action(s): Client should try the action again later. If error continually repeats, reboot InterMail servers.

Log Events


��/�4��*��.��

��/��

��

Description: The message store server temporarily locks a message or folder.

Parameters: None.

Cause: The MSS is performing an action for another client.


Action(s): Client should try the action again later. If the error continually repeats, reboot the MSS process.

Description: Attempted operation not supported for message store msName.

Parameters: operation: the attempted operation.

msName: the message store name.

Cause: Attempted operation not supported for message store msName.

Effect: The event is of minor severity. The impact on service depends on what the client requested of the MSS. Likely to affect a single message store only.


Description: An invalid property type requested of the message store.


Cause: An administration property designed for non-database message stores accessed on a database message store.


Action(s): • Check revisions of InterMail software.

• Contact your InterMail vendor.



��&��$�&��

��(/��

��-�*��/�4$��

Description: An attempt made by a client of the message store server to make the designated InBox folder in the folder folderName. Cannot create the folder designated as the InBox folder under a sub-folder. It must be a child of the root folder.


Cause: An client attempted to create an invalid InBox folder.



Description: Non-supported search operation searchOp invoked.

Parameters: searchOp: the searching operation.

Cause: An older version of InterMail server is running against a newer Message Store server.


Action(s): Check revisions of InterMail software. Upgrade the software or re-install as required. pkginfo -l InterMail will tell you the version number of the installed package on any host.

Description: An internal id refers to an object of an unknown type.

Parameters: None.

Cause:

Effect: The event is of minor severity. The effect on service depends on the circumstances that led up to the alarm.

Action(s): Check for other InterMail and system errors. Restart InterMail servers if error repeats more than every few minutes. If the error continues, contact your InterMail vendor.

Log Events


��-�*��

��-��#��

��+��

Description: MSS given a property that system does not recognize. This done either while attempting to set a property value, or during a request for the value of a property.

Parameters: None.

Cause:


Action(s): Check for other InterMail and system errors. Restart the InterMail servers if the error repeats more than every few minutes. If the error continues, contact your InterMail vendor.

Description: The version of the message store server does not support the requested query.

Parameters: None.

Cause: The version of the message store server is out of sync with some of the other servers.


Action(s): Check revisions of InterMail software. Upgrade the software or re-install as required. pkginfo -l Intermail will tell you the version number of the installed package on any host.

Description: An object from one message store given to another message store.

Parameters: None.

Cause: Probably memory corruption.

Effect: The event is of critical severity. It affects all message stores served by this MSS.

Action(s): The continued viability of the MSS is seriously in question. We recommend restarting the MSS. Check for other InterMail and system errors. If error continues, contact your InterMail vendor.



��+��/�4��$��

Message (Mail) Log Events

��,��1��

Description: A handle to an MSS object resolved but produced an object of the wrong type. The object name consists of messageStoreName : refNumber : typeName.

Parameters: objectName: the name of the MSS object.

realTypeName: the real type name of the object.

rmeOp: the most recent RME operation performed in this thread.

Cause: The Message Store Server is given a reference to a message that should be resolved to a message, but the MSS is unable to find the message requested, or otherwise does not recognize the reference that is being passed. It is possible that an incorrect reference (perhaps to a deleted message) causes this log event.

Effect: The event is of critical severity. Affects all message stores served by this MSS.

Action(s): • Check the log files for MSS client servers, including any customer software written to the API. Typically one of the access servers should also see an error, because their request to the MSS is not fulfilled.

• If the error is occurring from one of the native InterMail servers, contact your InterMail vendor for assistance.

Description: Attribute::getFromSrc() function called.

Parameters: None.

Cause: A class derived from the Attribute class without implementing a getFromSrc() member function.

Effect: This message is of major severity. It affects a group of message stores served by the erroneous server.

Action(s): If the error repeats more than every few minutes, restart the affected server. Contact your InterMail vendor.

Log Events


��.��'��(

��.��

Description: The header in the message had a content length field that was invalid. The current message will expand to include all content to the next From-line in the message input stream.

Parameters: char * context: the program context in which this event occurred.

int messageNumber: the number of the message in the mailboxFilename that was moving when this event occurred.

char * mailboxFilename: the filename of the mailbox that was moving.

Cause: Some message (either the current one or the next one) corrupted in some way. The file itself may be corrupted or this happened during writing the message. Stored messages may be lost. There is no way to recover what lost, except possibly by reviewing archived files.

Effect: The event is of minor severity. However, it is only reporting the error, not raising it, so that mailbox processing may continue.

Action(s): Review the file and compare with backups around the time the corrupted message received. Check for file system errors. If migrating a mailbox for the user, it may be necessary to re-initialize the mailbox and re-migrate, if the problem was due to a correctable file system error.

Description: Message received not properly encoded in uuencode() format.

Parameters: lineNumber: line number of ASCII message.

Cause: uuencode did not encode an enclosure properly. UUencoding only done for RFC1154 messages. By default, RFC1154 parsing is off, and under those circumstances this event should never appear. The configuration key convert1154ToMIME can turn on RFC1154 parsing.

Effect: The event is of minor severity. Affects an individual message only.

Action(s): No action is necessary. The system will re-interpret message as a text enclosure, package it in a MIME multipart enclosure along with some explanatory text, and deliver it to all recipients.



��.��"��,��

��.��"�!/��

��'��

Description: Could not parse a date-type header or enum-type header.

Parameters: headerLine: the header line from the original message.

lineNumber: the line number where the header was.

Cause: Date header or enum-type header improperly formatted

Effect: The event is of warning severity. Affects an individual message only.


Description: A bad object id in ASCII form for an enclosure type processed. Will ignore the remainder of file.

Parameters: hexOIDRep: the hexadecimal representation of an object id (OID).

Cause: The enclosure file is corrupt.



Description: Could not write an enclosure while writing a message to disk.

Parameters: pathName: the pathname to the tmp file.


Cause: This is probably a file system or hardware error.

Effect: The event is of minor severity (possibly major). It affects an individual message only if it happens occasionally. If the error repeats, it indicates a serious disk problem and the effect on service could become more serious.

Action(s): • Check system error status reported.

• Check to see if file system has run out of space.

• Check ownership and permissions of the tmp directory.

Log Events


��'��

�� .��'(��7

Description: The open(2) system call returned an error during an attempt to create an enclosure file.

Parameters: enclosureFilename: the filename of the enclosure.

functionName: open(2).



Effect: The event is of minor severity (possibly major). If this happens only occasionally, it will probably affect only individual messages. If error is frequent, it indicates a serious disk problem and the effect on overall service could become more serious.

Action(s): • Check system error status.

• Check to see the file system has not run out of space.


Description: An enclosure received in quoted-printable or base-64 encoding had an invalid character sequence.

Parameters: encoding: the encoding format.

badCharSeq: the bad character.

sequence.lineNumber: the line number where there is an error.

Cause: An improper character sequence read in a MIME enclosure encoded in quoted-printable or base-64 format.

Effect: The event is of warning severity. Affects only a particular message.




�� 1��

�� &��/��

��'��

Description: Call to getFromSrc made to the base class BodyType.

Parameters: None.

Cause:

Effect: The event is of major severity. Affects all users of the concerned server.

Action(s): Restart the affected server if the error occurs repeatedly. Contact your InterMail vendor.

Description: An attempt to write to a read-only tmp file.

Parameters: fileName: the name of the temporary file.

Cause: This is probably a file system or hardware error, or an operator error in changing permissions of InterMail tmp files.

Effect: The event is of minor severity. Affects a particular message, unless the file system or operator error impacts the entire tmp directory.

Action(s): Check permissions on files in tmp to verify that InterMail has access. Check for file system errors.

Description: A connection to the message store server closed while importing messages.

Parameters: None.

Cause: The connection closed because of a network error.

Effect: None.


Log Events


��

��/��)��

��/��

Description: Could not import file because it does not contain any recognizable mail messages.

Parameters: None.

Cause: This is probably a user error.

Effect: None.


Description: An attempt to import a file has failed.

Parameters: None.


Effect: None.

Action(s): Contact your InterMail vendor

Description: An attempt to open a file for importing failed.

Parameters: None.


Effect: None.




��&��

��

��

Description: Could not import the file because the message store server reported an error.

Parameters: None.


Effect: None.


Description: An attempt to stat a file to import failed

Parameters: None.


Effect: None.


Description: MultiPart::swapIn() called.

Parameters: None.

Cause:

Effect: The event is of major severity. It affects all users of the concerned server.

Action(s): Restart the effected server if the error occurs repeatedly. Contact your InterMail vendor.

Log Events


��/

��

��

Description: MultiPart::swapOut()called.

Parameters: None.

Cause:

Effect: The event is of major severity. Affects all users of the concerned server.


Description: Failed to move the message specified by the messageNumber in the specified mailBox_name.

Parameters: int messageNumber: the number of the message in the mailbox.

char *userId: the id (or account name) of the user.

char *mailBox_name: the filename of the mailbox that moved.

Cause: The message move failed for some unknown reason. Review the preceding log entries as well as any console messages for this mailbox and the .fail file.

Effect: The event is of informational severity. It is a notice of unexpected behavior.

Action(s): Review the events preceding this event as well as the .fail file generated by the application to determine appropriate action.

Description: Succeeded in moving the message specified by the messageNumber in the specified mailBox_name.

Parameters: int messageNumber: the number of the message in the mailbox.

char *userId: the id (or account name) of the user.

char *mailBox_name: the filename of the mailbox that moved.

Cause: This is expected behavior.


Action(s): None.



��.��

��

��/��$��

Description: MIME header indicating a multipart encountered but it did not specify the boundary parameter. See RFC1521 -- MIME (Multipurpose Internet Mail Extensions).

Parameters: None.

Cause: A bad MIME message read in.

Effect: The event is of warning severity. It affects a particular message only.

Action(s): No action is necessary. The system will re-interpret the message as a text enclosure, package it in a MIME multipart enclosure along with some explanatory text, and deliver it to all recipients.

Description: There was an empty file instead of an Internet message.

Parameters: None.


Effect: The event is of warning severity. It affects a particular message only.

Action(s): None. System will handle the message correctly. Check for file system errors.

Description: An object id for an enclosure type is too long. Will ignore remainder of file.

Parameters: objectId: the object id.

Cause: An object id was too long in the enclosure file.

Effect: None.


Log Events


��/��

��

Description: Could not open an enclosure of a message.

Parameters: enclosureFilename: the pathname to the tmp file.

function: open(2).



Effect: The event is of minor severity (possibly major). It affects an individual message only if it occurs occasionally. If the error repeats, it indicates a serious disk problem and the effect on service could become more serious.


• Check ownership and permissions of the tmp directory

• Check to see that the file system has not run out of space.

Description: A MIME partial message specified no id (for example, 1 of 4).

For more information, see MIME Spec RFC1521 (see section on Message/Partial subtype).

Parameters: None.

Cause: An improperly specified partial message received.

Effect: None.




�� /��

��&��

Description: Improperly encoded message received.

Parameters: encodingFormat: the encoding format.

lineNumber: the line number where the ASCII message ended prematurely.

Cause: In the message id, there was an enclosure encoded in Base64 or Quoted-Printable or RFC-1154 format, but an EOF encountered prematurely while processing it. See RFC1154 and RFC1521.

Effect: The event is of warning severity. Affects a particular message only.

Action(s): No action is necessary. The system will re-interpret the message as a text enclosure, package it in a MIME multipart enclosure along with some explanatory text, and deliver it to all recipients.

Description: Doing a read on the enclosure file resulted in a system error.




Effect: The event is of minor severity (possibly major): Affects an individual message only if it occurs occasionally. If the error repeats, it indicates a serious disk problem and the effect on service could become more serious.




Log Events


��* ��

��

Description: Could not seek an enclosure of a message.


function: lseek(2).





• Check existence, ownership, and permission of the file named.


Description: The stat system call returned an error on the enclosure file.






• Check existence, ownership, and permission of the file named.




��$��

��+��$��'��

MTA Log Events

��,��(��.��

Description: The action specified by actionPerformed performed on the message indicated by the tagged arguments in the logfile.

Parameters: actionPerformed: the action performed.

Cause: Expected behavior: These log entries are always at the Notification level, and enable tracing messages through the system.

Effect: The event is of informational severity. This is expected behavior.

Action(s): None.

Description: A subclass of Attribute failed to implement writeToInet().

Parameters: None.

Cause:

Effect: Affects all users of the afflicted server.

Action(s): Restart the effected server if the error occurs repeatedly. Contact your InterMail vendor.

Description: A client attempted to authenticate itself to the MTA using an invalid password.

Parameters: None.

Cause: • The client could have sent the password incorrectly.

• Not as likely, but the user's mail account could be set up incorrectly.


If this event occurs many times for a single connection it probably means that the account was not set up properly for that user. In this case, the event is of minor severity.

Action(s): Verify the user mail account information including password.

Log Events


��,��(��.��-��

��,��&��,��

��,��&��"��

Description: A client attempted to authenticate itself to the MTA using an invalid username.

Parameters: None.

Cause: • The client could have sent the user name incorrectly.

• The user's account information may be in the Integrated Services Directory.


Action(s): Verify that the user's account information is correct.

Description: Mail sent to an account that has vacation enabled, but no auto-reply message sent because the MTA has already sent one to this sender.

Parameters: None.

Cause: The “vacation” auto-reply mode requires only one vacation message sent to each user that sends mail to the auto-reply account.


Action(s): None.

Description: Mail sent to an account that has auto-reply enabled, but no auto-reply message sent because there was no recipient address in the To: or Cc: headers.

Parameters: None.

Cause: This most likely means that the mail came from a mailing list, so InterMail does not do the auto-reply in this case to prevent sending unnecessary auto-replies to mailing list posters.


Action(s): None.



��,��&��

�$,.��'��

Description: Mail sent to an account that has auto-reply enabled, but no auto-reply message sent.

Parameters: None.

Cause: Auto-reply not sent for one of the following reasons:

• the sender address is null.

• the sender address is in the autoReplySuppressList.

• the local part of the sender's address ends in “-request” or starts with “owner-”. This most likely means that the mail came from

• a mailing list.

• the message has “Auto-Forward:” in the header.

• the message has “Precedence: bulk” or “Precedence: junk” in the header.


Action(s): None.

Description: A control file lacks the pathnames to its header and body files. The control file contains this information so that the MTA can find the message contents. If this information is missing the message cannot be delivered. This should not happen in isolation. It is most likely the result of some other error.

Parameters: controlFileName: the name of the control file.

Cause: A control file was read by the MTA which either had missing or empty Header-File: or Body-File: attributes.

Effect: The event is of minor severity. Investigate this issue determine how this control file became corrupt. If this event is frequent, the primary cause of the error should be determined, since it is possibly causing other errors.


Log Events


��.��

��.��&��

Description: The file containing a message body could not move to a different location.

Parameters: oldMsgBodyFile: the name of the old message body file.

newMsgBodyFile: the name of the new message body file.


Cause: The system error should indicate the condition that caused the failure.


Action(s): Check the permissions on the directories containing the current file and the destination (and the directories leading up to them) to ensure that the MTA is able to perform the move.

Description: The MTA was unable to read a message body file.

Parameters: msgBodyFilename: the name of the message body file.



Effect: The event is of minor severity. An individual message is affected. The system defers the message in question.

Action(s): Check the permissions on the directory that would contain the file (and the directories leading to the file) to ensure that the MTA is able to create it. Recover the message file from backups or from journal file entries. If the error is occurring with multiple files, check the file system health.



��.��+��

��'��.��%��

Description: New message not created since the MTA could not write the file containing the message body.

Parameters: msgBodyFilename: the name of the message body file.




Action(s): Check the permissions on the directory that would contain the file (and the directories leading to the file) to ensure that the MTA is able to create it. Also, make sure the disk is not out of space.

Description: The control file for the message contains a parameter with an improper value.

Parameters: messageId: the message ID

controlFileParam: control file parameter.

controlFileParamValue: the value for control file parameter

Cause: • Some event external to the MTA (such as a disk error or manual editing) may have corrupted the control file.

• The permissions on the file (or any directory leading up to the file) prevent the MTA from reading the file.


Action(s): Check the permissions on the file to ensure that the MTA is able to read it. Inspect the file for obvious tampering or corruption.

Log Events


��'��

��'��&��

��'��+��

Description: The control file for a message could not move to a different location.

Parameters: oldControlFileName: the old control filename.

newControlFileName: the new control filename.





Description: The MTA could not read the control file for the message.

Parameters: controlFileName: the control file name.

sysErrorString: the system error string.

Cause: The control file may have become unreadable because of some event external to the MTA, such as a disk error or an unintended changing of the file’s permissions.


Action(s): Check the permissions on the file to ensure that the MTA is able to read it.

Description: The MTA could not write a new copy of the control file for a message.

Parameters: controlFileName: the name of the control file.




Action(s): Check the permissions on the control directory containing the file (and the directories leading to the file) to ensure that the MTA is able to create a new file and remove the original.



9�$,)��)��&��

�$,)��

Description: The MTA is unable to read the defer/MTA directory. This means that the MTA is unable to process deferred mail. The MTA continues attempting to read the directory every defer cycle.

Parameters: deferDirectoryname: the name of the control file.


Cause: This is most likely due to permission problems, but the actual reason is listed in the systemErrorString.

Effect: The deferred mail is not processed. If mail continues to be deferred, the defer directory will grow and the free space on the filesystem should be monitored. It is very likely that deferrals are also failing.

The event is of major severity. No mail that has been deferred for delivery is processed until the MTA reads this directory.

Action(s): Check the permissions on the defer directory. If the directory exists and is readable/executable by the commonUser, then contact your InterMail vendor.

Description: When the MTA is attempting to deliver previously deferred messages, the messages are moved out of the defer directory. If the MTA is unable to move the message, it does not reprocess the mail and the message is not delivered or bounced.

Parameters: controlFileName: the name of the control file associated with the message that cannot be reprocessed

reprocessDirectoryName: the directory into which deferred message control files are placed while being reprocessed.

systemErrorString: the system error message.

Cause: This is most likely caused by directory permissions or a problem.

Effect: In isolation, the event is of minor severity. This event can be the result of a configuration problem, permissions error, full file system, or other system problem. If any of these are the issue, it is likely that many of these errors will occur along with others. If this is the case, the event is of critical severity.

Action(s): Determine if the permissions on the directory allow the MTA (commonUser) write permission and then ensure that the file system and operating system are functioning properly.

Log Events


�$,)��'��(�)��

��)��$��

��)��$��

Description: This is not a log message. It is only used in the MTA as a deferral status.

Parameters: None.

Cause: The MTA is unable to communicate with the Directory Server for some reason.

Effect: The event is of information severity.

Action(s): None.

Description: An attempt to load the domain table from the directory failed.

Parameters: None.

Cause: The MTA cannot reach the ISD or the ISD is not working properly.

Effect: The event is of major severity. MTA cannot process mail until it can reach the ISD to retrieve the domain list.

Action(s): See if the ISD is up, and make sure the MTA can reach it. See if any related errors are in the MTA or ISD logs.

Description: Message deferred because the domain table not loaded.

Parameters: None.

Cause: The MTA cannot reach any ISD. This only happens on startup.

Effect: The event is of major severity. MTA cannot process mail until it can reach the ISD to retrieve the domain list.

Action(s): See if the ISD is up, and make sure the MTA can reach it. Then wait for the MTA to notice that the ISD is up (this takes up to one minute by default).



��)��$��-��

�� $��

Description: An attempt to update the domain table from the directory failed.

Parameters: None.

Cause: The MTA cannot reach the ISD, or the ISD is not working properly.

Effect: The event is of minor severity. The MTA will not receive notification of new domains added to the ISD and so will not begin accepting mail for these domains, until you fix the problem. Also, if the MTA cannot reach the ISD, it will not be able to process mail; if this is true, the log will report other errors.

Action(s): See if the ISD is up, and make sure the MTA can reach it. See if any related errors are in the MTA or ISD logs.

Description: System could not return to its sender a message that encountered an error, so it moved the message to the error directory. The contents of the control file are included to show what state the message was in.

Parameters: msgFileName: the file name of the message.

controlFileContents: the contents of the control file.

Cause: The error in the control file should indicate the reason the system could not return the message to its sender.


Action(s): Check the control file to see why system could not return it.

Log Events


��"��

��"��&��

Description: Could not move the file containing a message header to a different location.

Parameters: oldMsgHeaderFilename: the old name of the message header file.

newMsgHeaderFilename: the new name of the message header file.





Description: The MTA was unable to read a message header file.

Parameters: msgHeaderFilename: the name of the message header file.



Effect: The event is of minor severity. It affects defers an individual message.

Action(s): Check the permissions on the directory that contains the file (and the directories leading to the file) to ensure that the MTA is able to access it. Recover the message file from backups or from journal file entries. If the error is occurring with multiple files, check the file system health.



��"��+��

��"��$��

��"��&��

Description: The MTA was unable to create a new message because it could not write the header file.

Parameters: msgHeaderFilename: the name of the message header file.




Action(s): Check the permissions on the directory that would contain the file (and the directories leading to the file) to ensure that the MTA is able to create it. Also, make sure the disk is not out of space.

Description: One or more lines of the -Header file do not end with end of line characters.

Parameters: None.

Cause: While on disk, the -Header file was possibly corrupted.

Effect: The message cannot be delivered and is placed in the errors directory.

Action(s): Check the disk that the message was stored on (queueserver or mtaSpool directory) for disk errors or other problems.

Description: An attempt to change the header of a message failed.

Parameters: None.

Cause: • The machine ran out of memory.

• The machine ran out of disk space.

Effect: The current message will be placed in the deferred queue until system resources become available

Action(s): None.

Log Events


��"��

��!�$,"��'�� !��

Description: A message returned because the host it relayed to does not exist.

Parameters: None.

Cause: Someone attempted to use the server to send a message to a remote server, but there was no server in the DNS.


Action(s): Check the host to see if it exists. If so, there may be a problem with the DNS. If not, then the message simply had an incorrect address.

Description: A message came into the MTA with more Received: lines than is allowed by the maximumMTAHops configuration key. This means that the message has passed through too many hops on its way to this server, which probably means that a mail loop has occurred.

Parameters: maxHopCount: the maximum number of hops allowed.

Cause: A mail loop is most likely responsible. A forwarding loop could cause this. Part of the cause of the problem may exist on another server.


Action(s): Check the Received: lines of the message to figure out which other server is routing mail back to this site, and which account is responsible. Contact the postmaster of the remote site, turn off forwarding on the local user’s account, or warn the local user that the forwarding is causing problems.



��#��)��(

��#��$��

Description: There was a message queued for outbound delivery in the wrong spool directory. The name of the directory did not match the Host-To: line in the control file.

Parameters: oldQueueDir: the name of the spool directory the control file was in.

newQueueDir: the name of the spool directory the control file moved to.

Cause: Control files possibly moved manually without changing the Host-To: line.


Action(s): If control files must move to a different queue directory, make sure to modify the Host-To: line.

Description: A message queued for outbound delivery returned because it was in the queue too long.

Parameters: None.

Cause: A remote server has been unreachable for too long. The dispatch/config/maxQueueTime configuration key determines the maximum queue time.


Action(s): Determine if the remote site still exists and is reachable. If not, then contact that site to determine the problem.

Log Events


��&��

��

Description: An error occurred that normally causes the message to be returned to the sender. However, when submitting the message, the sender specified that failure notifications should not be generated. So, no notification is given to the sender.

Parameters: errorType: the name of the error that is causing the bounce.

Cause: The sender is requiring no failure notifications.


Action(s): None.

Description: Attempts to secure a message in the spool directory were unsuccessful. (If there is more than one MTA, attempts made to secure the message on each of the spool directories were unsuccessful.) Consequently, the system rejected the message.

Parameters: None.

Cause: The MTA is not working properly.

Effect: The event is of urgent severity. If the system cannot secure messages, the MTA cannot properly process mail. The system will reject any mail that it cannot deliver immediately.

Action(s): Check the MTA logs for related messages.



��,��(

��$��

Description: A client attempted to send mail through the MTA using a sender address that requires authentication, but the client did not authenticate itself first.

Parameters: None.

Cause: • The user's client may have an incorrect configuration.

• The user's account information may not appear in the Integrated Services Directory properly.

• The user may be using a client that does not support SMTP authentication.


Action(s): • Verify that the user's account information is correct.

• Change the /*/mta/checkAuthorization key to false.

Description: Message rejected by a remote server because it was too large.

Parameters: msgSize: the size of the message in bytes.

allowedSize: the max size allowed by the remote server.

Cause: Someone attempted to use the server to send a message to a remote server, but the server rejected it as being too large.


Action(s): Send smaller messages, or contact the remote site and tell them to increase their size limit.

Log Events


�$,��&��

��(��!��

��#��)��&��

Description: The validator thread is processing a message to find out the required delivery type, but no deliveries are resulting.

Parameters: msgId: the message ID of the message that is being processed.

Cause: This could be caused by a forwarding loop, or by an account with neither POP delivery nor forwarding turned on. The MTA moves the message aside into the errors directory so that it does not get lost.

Effect: The event is of error severity. The mail is held in the errors directory and is not processed until it is moved back into the defer directory. The recipient accounts may not be able to receive mail until they are fixed.

Action(s): Check recipient accounts for forwarding loops or turn off all delivery flags. This condition should be fixed so that mail can be delivered properly to them.

Description: When trying to send a file to the spool directory, the MTA was unable to remove the local filename prefix because it was not present.

Parameters: fileName: the filename that has the invalid prefix.

prefix: the prefix that the MTA was attempting to remove

Cause: This is an internal error caused by an abnormal filename and should not happen in normal operation.



Description: A spool directory removed after the messages in it were processed.

Parameters: dirName: the name of the queue directory removed.

Cause:


Action(s): None.



��#��(

Description: The MTA maintains consistency with the imqueueserv through the use of iteration numbers. Any time the MTA disconnects from the imqueueserv and re-connects (for instance, the imqueueserv was rebooted), then the iteration number for the imqueueserv is incremented. Each message that the the MTA is currently manipulating on the imqueueserv is also tagged with that same iteration number. It should therefore always be the case that the iteration number of the message matches the MTA’s iteration number for the imqueueserv. If the iteration number doesn’t match, then the MtaQueueServerIterationMismatch event is logged.

Note that the iteration number is not maintained with the file, so a deferred piece of email does not maintain the iteration number it had while the MTA was processing it. When the MTA re-processes that deferred email message, it will get assigned a new iteration number that matches the current iteration number of the imqueueserv connection. The iteration number is only maintained for messages that are currently being processed by the MTA and are secured on the imqueueserv.

Parameters: filename: The file that the MTA attempted to use.

operation: The operation that the MTA attempted to do with the file.

queueserver iteration number: The MTA’s queueserver connection number MTA iteration number.

mta iteration number: The mesage’s queueserver connection number.

Cause: Unclear. This should not happen during normal operation

Effect: The MTA will stop handling that message. It may re-process it later, or it may have already been processed and needs to be removed.

Action(s): This event should not affect mail delivery but should be reported to your InterMail vendor.

Inspect the mta.log to see if the message was delivered; if so, simply remove it. Otherwise make sure that the message Control file is in queue/deferred/MTA and that the corresponding Header and Body parts exist under queue/messages.

Log Events


��&��&�4��

��&��$��

��&�4��

Description: Message rejected by a remote server because one or more recipients refused.

Parameters: None.

Cause: Someone attempted to use the server to send a message to a remote server, but the server rejected it (or at least rejected some of the recipients) because the recipients were refused.


Action(s): Check the message reported by the server, and see if there is anything obviously wrong with the recipients. Most likely, this is a problem with the remote server, though, since the MTA validates recipient addresses before accepting mail.

Description: An error occurred when trying to parse a line in the mail routing table.

Parameters: entry: the entry that caused the problem.

Cause: The line is malformed or otherwise invalid.

Effect: The event is of minor severity. It ignores the invalid line.

Action(s): Fix the invalid line in the mail routing table and update the MTA configuration.

Description: Message rejected by a remote server because the sender refused.

Parameters: None.

Cause: Someone attempted to use the server to send a message to a remote server, but the server rejected it because the sender refused.


Action(s): Check the message reported by the server, and see if there is anything obviously wrong with the sender. Most likely, the remote server caused this event, since the MTA validates sender addresses before accepting mail.



��.��&��

��'��

��)�,��*��

Description: Message deferred because the remote server gave an unexpected response.

Parameters: None.

Cause: Some sort of problem on remote server. Check the server response in the log message, if any, to try to determine the cause.


Action(s): Wait for spool reprocessing and mail redelivery. If the condition persists, and the host is reachable, try sending a simple message to that host to see if any mail is getting through.

Description: Message deferred because the MTA could not connect to a remote server.

Parameters: None.

Cause: Some sort of problem on remote server, possibly temporary.


Action(s): Wait for spool reprocessing and mail redelivery. If the condition persists, and the host is reachable.

Description: Message deferred because the MTA could not retrieve a DNS A record for the server.

Parameters: None.

Cause: A problem on the remote DNS server, possibly temporary.


Action(s): Make sure the MTA’s DNS server is working properly. Then check to see if the remote host can do DNS lookups. If not, wait for spool reprocessing and mail redelivery.

Log Events


��)��K��*��

��

��*��'��

Description: Message deferred because the MTA could not retrieve a DNS MX record for the server.

Parameters: None.

Cause: Some sort of problem on the remote DNS server, possibly temporary.


Action(s): Make sure the MTA’s DNS server is working properly. Then check to see if The remote host can do DNS lookups. If not, wait for queue reprocessing and mail redelivery.

Description: A message deferred because the remote server gave a 4xx response, or otherwise failed to accept the message.

Parameters: None.

Cause: A problem on remote server, possibly temporary. Check the server response in the log message, if any, to try to determine the cause.


Action(s): Wait for queue reprocessing and mail redelivery. If the condition persists, and the host is reachable, try sending a simple message to that host to see if any mail is getting through.

Description: Message deferred because the connection to the remote server closed.

Parameters: None.

Cause: The remote server most likely went down.


Action(s): Wait for spool reprocessing and mail redelivery. If the condition persists, and the host is reachable, try sending a simple message to that host to see if any mail is getting through.



��$��/��

��,��

��,��

Description: Message deferred because the connection to the remote server timed out.

Parameters: None.

Cause: The remote server most likely went down, or the network connection to it broken.


Action(s): Wait for queue reprocessing and mail redelivery. If the condition persists, and the host is reachable, try sending a simple message to that host to see if any mail is getting through.

Description: A user attempted to send mail through the MTA, but that user’s account does not have SMTP service enabled.

Parameters: None.

Cause: The user’s account information may not appear in the Integrated Services Directory properly. Or, maybe the client is just using SMTP when he or she shouldn’t be.


Action(s): Verify that the user’s account information is correct.

Description: A user attempted to send mail through the MTA in SSL mode, but that user’s account does not have SMTP SSL service enabled.

Parameters: None.

Cause: The user’s account information may not appear in the Integrated Services Directory properly. Or, maybe the client is just using SSL when he or she shouldn’t be.


Action(s): Verify that the user’s account information is correct.

Log Events


��$��

��$��&'�$�

Description: Message sidelined because sent from the null address < > and addressed to more than one recipient.

Parameters: None.

Cause: This warning appears when sidelineNullToMany is turned on by the configuration database and a message comes in from < > to more than one recipient.


Action(s): This is a frequent warning message. One option is to change the value of the sidelineNullToMany configuration key to false in the configuration database.

Description: Message sidelined because it has too many recipients

Parameters: None.

Cause: The configuration database defines the maximum number of sideline recipients. This warning appears with a message addressed to more than the maximum number of recipients.


Action(s): This is a frequent warning. One option is to increase the maximum number of recipients in the configuration database.



&��"��)��

Network Input/Output Log Events

��,��

Description: The IP address was labeled as a source of RCPT TO: harvesting, and therefore we dropped the connection before they could connect to our MTA. They were labeled an RCPT TO: harvester due to the number of bad RCPT TO:’s they generated.

Parameters: IP - The IP address of the client trying to connect.

Cause: They previously issued a number of bad RCPT TO:’s and got labeled an RCPT TO: harvester, according to the config.db settings.

Effect: The connection from the client was dropped. There is no effect on service for other IPs.

Action(s): Investigate the source of the IP address in question. Look through the mta.log for bad RCPT TO:’s coming from that IP address. The marker that the IP address is a RCPT TO: harvester will eventually time out, as specified by the config.db settings.

Changing /*/mta/trackRcptHarvesters to false or restarting the MTA would allow that IP to establish an SMTP connection to the MTA.

Description: When attempting a connection to a socket, the accept system call returns the error systemErrorString.


Cause: • Insufficient memory to complete the accept.

• Insufficient STREAM resources to complete the accept.


Action(s): Use the systemErrString to determine the cause of this event.

Log Events


��.��

��.��#��'��

��.��

Description: The server program attempted to get from the configuration database the number of the port that it should listen on, but the entry is not a valid port number.

Parameters: paramName: the name of the configuration key holding the port number.

Cause: Invalid entry for the configuration key.

Effect: The server will not run.

Action(s): Use imconfedit and edit the appropriate configuration key.

Description: A bad encoded query type queryType received.

Parameters: queryType: the query type.

Cause:

Effect: The event is of minor severity. It is major if it occurs frequently.


Description: Attempted to bind to a socket that failed with system error systemErrorString. The port number is portNum. The system call was to bind.

Parameters: portNum: the port number.


Cause: This event occurs at startup of a server when the server attempts to bind to a TCP/IP port and either that port is in use or the server did not start properly. It could also be that the system has insufficient stream resources.

Effect: The event is of critical severity. If the MSS process signals this event, the users cannot fetch existing mail.

Action(s): Verify program started by the correct user (usually root). If not, this would be the reason why the program does not have adequate permissions.



��.��

��.��

Description: The system call to bind failed with systemErrorString. This bind socket connection was between a client and a server both running on the machine localhost.

Parameters: localhost: the name of the local host.


Cause: • Program does not have adequate permissions to access address.

• Insufficient STREAM resources.

Effect: The event is of critical severity. If the MSS process signals this event, users cannot fetch existing mail.

Action(s): Verify program started by the correct user (usually root). If not, that might explain the inadequate permissions.

Description: Attempted to bind to a socket that failed with system error systemErrorString. This happens in the MTA.

Parameters: pgmName: the program name.


Cause: • Program does not have adequate permissions to access address.

• Insufficient STREAM resources.

Effect: The error is minor in that it defers mail because the MTA is not running. It is critical from the system viewpoint because the MTA is probably not running.

Action(s): Verify program started by the correct user (usually root). If not, that might explain the inadequate permissions.

Log Events


��'��*��

��'��,��

Description: The call to close the socket to host failed with system error systemErrString.

Parameters: host: the name of the host machine.


Cause: • The server that manages the connection could have died.

• The socket is on a remote machine and the remote machine is not behaving as expected.


Action(s): Verify that the server in question and the remote machine are OK.

Description: The server detected an illegal attempt to connect to a server port by the host at IP address ipaddress but the attempted connection drops since that IP address is not in the access list for this port (stored in the configuration database under accesstype).

Parameters: ipaddress: the IP address of the machine that is being rejected.

keyname: the configuration key that controls this type of access.

Cause: The access control list does not allow connections from the given IP address.

Effect: None. This might be a warning of an attempted intrusion to the machine, however, so investigate the IP address listed to determine why it is attempting to connect. It might also be possible that if the access control lists for this port are incorrect, a host that should be able to connect is being denied service.

Action(s): If the message is frequent or concerning, verify the access control list, and determine which remote host is attempting access.



��'��

��'��$��

Description: This program could not connect to the server serverName on host hostname with port portNum.

Parameters: serverName : the name of the server

hostName: the name of the host on which the server was running.

portNum: the port number that the server was using.

Cause: • The server may be down or in a strange state.

• The port number may be incorrect for communication with the server.

• The host machine for the server may be in a strange state.

• Heavily loaded system.

• Network problem between host machine and the machine on which this program is running.

Effect: The event is of major severity in the context of one of the servers.

Action(s): Verify that the server and host machine are OK and running. Verify that the port number portNum is correct. These may be incorrect due to configurations out of sync on different hosts. Correct the problem and restart the appropriate servers.

Description: The call to connect to the server running on host timed out. The process could not establish a connection with the server on machine host.

Parameters: server: the name of the server.

host: the name of host on which the server is running.

Cause: The server or host machine host could be in a strange state. This could indicate that the server cannot connect to the MSS.


Action(s): Check the log file for the server to verify that it is OK. Verify that the host machine host is up and running. If the server is in a strange state, restart that server.

Log Events


��'��&��

��'��$��.��

Description: Could not establish a connection to the server that is on host. The read() system call returned with systemErrorString.

Parameters: server: the name of the server.

host: the name of the host machine.


Cause: • Host that server should be running on, is in a strange state.

• Server may not be running or could be in a strange state.


Action(s): Use the system error information systemErrorString to determine the cause of this event. If the server is in a strange state or has gone down, restart it.

Description: An entry for the limit of connections for an IP address is invalid. Each entry must be of the form: ip_address

/significant bits] : num_connections

This event occurs if the entry is not in this form.

Parameters: None.

Cause: Invalid entry in the config.dm form for the config key clientConnectionLimitTable.

Effect: This affects the MTA. If this event occurs the table entry is ignored.

Action(s): Change the bad entry of clientConnectionLimitTable in the config.db form using imconfedit.



��'��*��

��

Description: Attempted to create a socket, calling socket with the arguments format PF_INET and type SOCK_STREAM, returned system error systemErrorString.

Parameters: prgm: the name of the program.


Cause: • The program does not have the proper permissions to create sockets.

• Insufficient user memory available.

• Insufficient system resources available.

Effect: The event is of minor severity if this event occurs infrequently. It does not affect users being able to retrieve mail. If this event occurs more often, it is an indication that there is something seriously wrong with the host machine.

Action(s): Verify that the program started with the correct permissions and with the correct user. If system and memory resources are exhausted, work to free up allocated resources.

Description: An event mask eventmask specified for file descriptor filedesc which is not supported.

Parameters: eventmask: the event mask.

filedesc: the file descriptor.

Cause:



Log Events


��

��$��

��#��

Description: The call to fcntl() failed with error systemerrstring.

Parameters: systemerrstring: the system error string.

Cause: It could be one of several causes. The systemerrstring should indicate the reason.


Action(s): None.

Description: The filename exceeds the length of maximum filename for internal storage in the InterMail system.

Parameters: filename: the file name.

length: maximum length of file name.

Cause:

Effect: The event is of minor severity. It does not have any effect on retrieving mail.

Action(s): Verify that the system has correct configuration and that the data files are in the correct locations.

Description: While waiting for input on a socket on host an unexpected value returned (systemErrorString). The process received a Quit request while waiting for input on a socket to host.

Parameters: host: the name of the host.


Cause: • Not enough memory for poll to complete.

• Signal caught while performing poll.

Effect: The event is of minor severity when in the context of the MSS, POP Server and other servers.

Action(s): Use the system error systemErrorString to determine the cause of the event.



��"��

��1��

Description: Getting the host name failed for host, the system call was systemcall, which returned systemErrorString. The process could not find a hostname for the particular address.

Parameters: host: the host name.

systemcall: the name of the system call.


Cause: The cause depends on the system call.


Action(s): Use the systemcall and the error information systemErrorString string to determine what is wrong.

Description: Attempted to get the socket name with the call to getsockname, which failed with system error systemErrorString. This happens when the MTA is getting the socket name that it is bound to.

Parameters: pgmName: the program name.


Cause: • Insufficient memory for operation to complete.

• Insufficient STREAMS resources.

Effect: The event is major severity for the MTA.

Action(s): Using the system error information systemErrorString determine which condition caused this event.

Log Events


��

��!'��

��

Description: The system call to listen failed with system error systemErrorString, when the process was establishing a connection with a client.


Cause: Network problems.


Action(s): Using the error information, determine the cause of the error. If this event occurs repeatedly, investigate network problems.

Description: The server has hit the maximum number of connections, and will not accept additional connections until other clients disconnect.

Parameters: count: the maximum number of connections.



Action(s): If these messages persist, consider raising the connection limit, or add additional servers for an overloaded server.

Description: The server program attempted to get from the configuration database the number of the port that it should listen on, but either the entry was missing in the database or its value was explicitly zero.


Cause: Missing or invalid entry for the configuration key.


Action(s): Use imconfedit to add the appropriate configuration key.



��

��.��&��

Description: The file has either read/write permissions by group or no read/write permissions by owner.

Parameters: file: the file name.

Cause: • The server may not have started with the correct user.

• The system may not have the correct configuration.

• The file may be in the wrong location or could have the wrong permissions.


Action(s): Verify that the process started with the right user. Verify that the system has the correct configuration and that the file it is accessing is in the right location and has the correct permissions.

Description: The value returned from the system call to poll() where poll called pollCallInfo returned the error pollCallRes. poll returned a value other than 0 or -1.

Parameters: pollCallInfo: how poll called with arguments.

pollCallRes: the results from poll.

Cause: The file descriptor returned by poll is not the expected file descriptor.

Effect: The event is of critical severity in the context of the MSS or the POP Server. The event is of major severity in the context of the MTA. servers.

Action(s): Use the information from pollCallInfo and pollCallRes to determine what caused the event.

Log Events


��

��

��

Description: The system call to poll() failed. (Information determined from the error set by poll().) After encountering this event, the socket closed.

Parameters: reason: explanation why poll failed.

Cause: • Error occurred on device or stream

• Hang up on the stream.


Action(s): Determine the cause of the event. Check the general health of the host machine that this process is running on.

Description: While waiting for input on a socket, the system call to poll() failed with system error systemErrorString. A network connection closed or a system error occurred.


Cause: • Not enough memory for poll to complete.

• Signal caught while performing poll.


Action(s): Use the system error systemErrorString to determine the cause of the event.

Description: The server program attempted to get the number of the port that it should listen on. But the entry is a number that is not appropriate for this server.


Cause: Invalid entry for the configuration key.


Action(s): Use imconfedit to edit the appropriate configuration key.



��&��*��

��&��

��&��

Description: The attempt to read from the socket failed. Specifically, the call to recvfrom returned the system error systemErrorString. This happens in the context of the MTA only.


Cause: Probably insufficient user memory.

Effect: The event is of major severity in the context of the MTA.

Action(s): Use the systemErrorString to determine the cause of this event. Check the general health of the system and the host machine on which this process is running.

Description: The system call to recv failed. This is due to either a system error or a network connection problem.

Parameters: None.

Cause: System error or network connection problem.


Action(s): Look in the logs for events that would indicate either a system error or network connection problem.

Description: The system call to recv failed. This is due to either a system error or a network connection problem. Matches NIORcvErr.

Parameters: None.

Cause: System error or network connection problem.


Action(s): Look in the logs for events that would indicate either a system error or network connection problem.

Log Events


��$��/��

��1��)��

Description: A network connection closed.

Parameters: sockdes: the socket descriptor.

Cause: The host machine is in a strange state, or there are other network problems.

Effect: The event is of minor severity in the context of one of the servers.

Action(s): Verify that the host machine is OK. Verify and fix network problems.

Description: A server that this program connected to has gone down. The MTA believes that a server that it is communicating with has terminated.

Parameters: serverName: the name of the server.

hostName: the name of the host that the server was running on.

portNum: the port number that the server was using.

Cause: There could be a number of causes for this event. The underlying problem is that a server went down when it should not have.

Effect: The event is of critical severity in the context of the MTA.

Action(s): Verify the state of the server that this process connected to. If the server is not running, determine the cause and restart.



��.��0��

��!��

Description: The attempt to set the buffer size for input on the socket failed. A call to setsockopt does this. This only happens in the MTA. The size of the buffer was 64K, a maximum under Solaris 2.4.

Parameters: bufSize: the buffer size in bytes.

pgmName: the program name.


Cause: • Incorrect software configuration.

• Insufficient memory available.

• Insufficient STREAMS resources.

Effect: The event is of major severity in the context of the MTA.

Action(s): Using the information from systemErrorString, determine the source of the problem. If memory or STREAMS not insufficient, contact your InterMail vendor.

Description: When starting up a server the number of requested file descriptors exceeds either the soft or hard limit. Calling setrlimit does this.

Parameters: curNumDesc: the current number of file descriptors.

softDescLimit: the soft limit on the number of file descriptors.

hardDescLimit: the hard limit on the number of file descriptors.

user: the user running this process.

Cause: The server may not have started by root, in which case it will not be able to get the requested number of file descriptors. The number of file descriptors may be wrong.

Effect: The event is of critical severity in the context of one of the servers.

Action(s): Verify that the server started by root. Verify that the requested number of file descriptors is correct.

Log Events


��)��

��*��

��*��'��

Description: The attempt to set socket to non-blocking mode failed with system error systemErrorString. The system call is fcntl.


Cause: • Permissions problems due to server started up with wrong user.

• Configuration


Action(s): Verify that the process started with the correct server. Verify that the system configuration is correct.

Description: The call to setsockopt() failed with system error systemErrorString. This only happens in the context of the MSS.


Cause: Probably insufficient memory or insufficient STREAMS resources available.

Effect: The event is of major severity in the context of the MSS.

Action(s): Using the systemErrorString determine if the cause is insufficient resources or programming error.

Description: The network connection to a client or server on host has been lost.


Cause: A network connection closed, or a system error occurred.


Action(s): This is a lower level signal. Investigate the logs for more serious events. Troubleshoot that event.



��*��

��*��/��

��

Description: The system call to socket failed with error systemErrorString.


Cause: • The program does not have the proper permissions to create sockets.

• Insufficient user memory available.

• Insufficient system resources available


Action(s): Verify that the program started with the correct permissions and with the correct user. If there is no obvious problem with system or memory resources, work with your InterMail vendor to free up allocated resources.

Description: Could not terminate a network connection to host properly because of a problem with closing the socket.


Cause:



Description: After doing a stat on the file it determined that it was stale. (Deduced by determining that the file access time, modification time and status change happened earlier than 30 seconds before the stat on the file.)


Cause: File removed during access.


Action(s): Verify that the file exists.

Log Events


��

Parameter Log Events

��/��

Description: The attempt to get statistics on the file failed. Specifically, the system call stat failed with error systemErrorString.



Cause: • Permissions may not be right for process and/or file.

• The file may no longer exist.


Action(s): Use the systemErrorString to determine the cause of this event.

Description: Command line argument specified for starting the MSS not recognized. Displays “The command line option %s does not start with - and is too short (only one character).”

Parameters: cmdlineopt: the command line option.

Cause: The command line argument for starting the MSS does not start with a - or it is not of the form -c, where c is a single character.


Action(s): Verify the script or command that started the MSS to determine the valid and invalid command line arguments.



��-�*��/��

POP Server Log Events

��'��

Description: Command line argument specified for starting the MSS not recognized. Displays “The command line option %s is not recognized by this program.”

Parameters: cmdlineopt: the command line option.

Cause: The command line argument is the right form but is not recognized.


Action(s): Verify the script or command that started the MSS to determine the valid and invalid command line arguments.

Description: The POP Server encountered an error when trying to communicate with the MSS. Displays “Pop communications failure with message store server, disconnecting user.”

Parameters: None.

Cause: Typically caused by a problem with the MSS. The MSS could be in a strange state. The machine that the MSS is running on, which this POP Server is communicating with, could be in a strange state.


Action(s): Check the log file for the MSS that this POP Server is communicating. Probably other errors are a better indication of what is wrong with the MSS.

Log Events


��'��,��

��'��

��'��$��/��

Description: IP Address is attempting to connect to the popserv but is denied because the address is not listed in the allowedIPs configuration key.

Parameters: IP Address.

Cause: The allowedIPs configuration key specifies the IP addresses from which the popserv accepts connections. Unlisted IP addresses have their connections dropped immediately.

Effect: No effect on service; prevents POP attacks.

Action(s): None.

Description: The POP Server successfully validated the user. This is a notification in the logfile. It is not an error event.

Parameters: None.

Cause: The user being successfully validated by the POP Server.


Action(s): None.

Description: A POP communication with a client has timed out and subsequently disconnected.

Parameters: None.

Cause: A connection between a client and the POP server was established, but the client has not sent command data to the server within the configurable timeout period (popClientTimeout).

Effect: If this occurs, the POP server thread terminates the client connection and exits.

Action(s): If the time out period is not long enough, modify parameter popClientTimeout in the configuration database appropriately. Otherwise, reconnect to the POP server and continue where you left off.



��)��$��

��*$��$��,��

Description: At least one of the values in the loginDefaultDomainTable (found in the config.db) contains an entry which does not follow this format:

<ipaddr>:<defaultDomain>

Parameters: The table entry which caused the problem

Cause: An entry in the loginDefaultDomainTable was incorrectly entered into the config.db.

Effect: The loginDefaultDomainTable entry mentioned in the log message, as well as any entries that follow it (within the loginDefaultDomainTable table), is ineffective.

Action(s): Make the appropriate corrections to the loginDefaultDomainTable, using imconfedit. Do not restart services.

Description: Indicates the popLockTimeout configuration key might be too low.

Parameters: None.

Cause: A POP user’s exclusive POP lock timed out, but the user was subsequently active.

Log Events


Effect: When a POP client successfully logs on to the POP server, it receives an exclusive lock on its mailbox. If there is an attempt to log on to the same mailbox with the exclusive lock, it refuses the attempt with an error message. A POP client normally holds the lock until it Quits. The POP3 specification demands exclusive locking.

Unfortunately, a user can end up locked out of his or her own mailbox, causing calls to customer support. This parameter is to control a common cause of these complaints. A communications transport implementation weakness (not part of InterMail) can cause the POP server to believe a connection with a POP client is still open, when in reality the POP client got hung up on. When the user redials and attempts to access his or her mailbox, he or she gets rejected with a message that his or her mailbox is exclusively locked—a message the user is probably not used to seeing. The popClientTimeout will eventually cause the connection to close, but many users will lose patience and call customer support before it kicks in.

If a POP client is idle for the popLockTimeout, it loses its exclusive rights to the lock, and shares it with the next client that requests it.

If it hangs up on a user, the default popLockTimeout value will take away the exclusive right to the lock from the dead connection before the user has the time to dial back in. Once the user is connected, she will be able to successfully log on and access her mailbox, because the new session will be able to share the lock with the dead one. The popClientTimeout will subsequently kill off the dead connection for good.

Software POP clients access a mailbox in a rapid fashion; it should be very rare in practice to see a popLockTimeout kick in when the POP client is still interested in the connection. When this rare case does occur, the POP server records the PopLockTimeoutTooAgressive notification log message.

When a popLockTimeout does occur to an active session, ill can come of it only if another session grabs the lock. The original session and the new session will both share the lock. The worst that can happen is for one session to delete a message that the other session subsequently tries to retrieve, causing the retriever to get an error.

More typically, an active session that suffers a popLockTimeout will send a command to the POP server before another session tries to access the mailbox. In this case, the POP server grants the exclusive lock to the session again, and the session continues just as if the popLockTimeout never occurred.

Action(s): Lots of these events in the log are a symptom of the popLockTimeout configuration key being too low. Adjust it up.



��!��

��

Description: The POP Server is hitting the maximum number of connections configured by the system administrator, and does not accept additional connections until other clients are disconnected. The maximum connections allowed is configured using the /*/popserv/maxSessions keyword within the configuration server (imconfserv). Setting the maxSessions to the default [0] disables this feature.

Parameters: count: the maximum number of connections



Action(s): If these messages persist, consider raising the connection limit, or add additional servers if the server is already overloaded.

Description: While verifying the user and password, the MSS was unavailable. Displays “User's MSS is currently inactive.”

Parameters: None.

Cause: Something is either wrong with the MSS or the machine on which the MSS is running. Note that the event that caused this is AcctInactive.


Action(s): This is not typically a problem with the POP Server. Check the status of the MSS with which this POP Server was communicating. Check the machine on which the MSS is running.

Log Events


��

��!��)��

Description: This event occurs when the POP Server receives a command from a POP client that is not part of the POP protocol (from the server’s point of view). It is not a serious error.

Parameters: cmd: the POP command.

Cause: The POP client sends a command that is not in the POP set of commands.

Effect: The event is of warning severity. This is not serious and indicates a problem with the client software.

Action(s): None. See man page on POP Server and Post Office Protocol and Post Office Protocol extensions.

Description: The POP server has been configured to proxy connections back to its own incoming POP port. This will cause the POP server to loop to itself, and use up all available connection threads, denying service to other incoming clients. The incoming connection is closed.

The pop proxy host is configured using the /*/popserv/popProxyHost keyword within the configuration server (imconfserv).

The pop proxy port is configured using the /*/popserv/popProxyPort keyword within the configuration server (imconfserv).

One or both of these values must be configured to a value other than the one currently in use by the popserv that is being configured.

Parameters: None.

Cause: The popserv has been configured to proxy all incoming connections back to itself, causing an infinite loop.

Effect: The event is of urgent severity. Users are prevented from collecting their mail while this condition exists.

Action(s): Immediately after receiving this message, the POP proxy settings should be reviewed, and the settings should be changed to appropriate new values.



��

Process Log Events

��,��

Description: Synchronization error with MSS; got reply reply in state “state.”

Parameters: reply: name of the unexpected reply received.

state: state of the POP connection when the reply received.

Cause: The MSS or POP Server could be in a strange state.

Effect: May indicate a problem with the MSS or the POP Server. Clients may not be able to access mail using POP.

Action(s):

Description: An assertion in the source code failed.

Parameters: assertion: the assertion that failed.

fileName: name of the source file.

lineNumber: line number in the source file

Cause: An assertion failed at run-time.

Effect: Depends on the assertion.


Log Events


��.��'��

��.��

Description: This event should not occur in normal operation. While this is suspect, it should not cause any problems. This event indicates that the MTA and the MSS are out of sync.

Parameters: stateCode: the state code of the Deliverer thread.

lineNumber: the line number of the source file.

Cause: A Deliverer thread in the MTA received a response from the MSS that it did not expect in its current state.

Effect: The event is of warning severity. Will temporarily defer the message under delivery.

Action(s): In isolation, this event is harmless. If the error occurs regularly, it may indicate problems with the MSS, MTA, one particular mailbox, or one particular host. If the error is isolated to one of these components, restart or repair that component as appropriate.

Description: Section of code entered that should never happen.

Parameters: fileName: name of the source file.

lineNumber: line number in the source file

Cause: Must be determined from source code.

Effect: Must be determined from source code.




��.��'��

��'��1��(

��'��

Description: Broadcasting of condition resulted in an error. The current release of the product does not broadcast conditions, so this should never happen.

Matches: ThrdBroadcastingCond

Parameters: conditionName: the name of the condition.


Cause: There is no known cause for this event.

Effect: The event is of major or critical severity. The effects are unknown.

Action(s): Restart the server reporting this event.

Description: The path to the executable for this program cannot be determined.

Parameters: pathToExecutable: the path to the executable program.

Cause: The program is invoked without an absolute or relative preceding path, for example, it is invoked as popserv.

Effect: None, except that the server does not start this way.

Action(s): This problem does not occur when InterMail servers are launched using imservctrl, which is the recommended. If you must start it manually, add at least a relative path to the program name, for example, lib/popserv.

Description: Could not kill the process.

Parameters: process: the name of the process program.

pid: the process id.


Cause: The call to kill(2) failed. Check the man page for the exact meaning of the systemErrorString for this function.

Effect: None, except that the process not killed.

Action(s): Make sure that imservcall runs as root or as the commonUser.

Log Events


��'��&��

��'��&� !��

��'��

Description: The contents of the pid file did not translate to a valid process id.

Parameters: pidFileName: the name of the pid file.

Cause: The program imservcall found a pid file, but could not convert the contents of the file to a valid, non-zero process id.

Effect: None, except that the program imservcall will not be able to stop the server.

Action(s): Without a pid file, must kill the process manually by determining its process id using ps(1) and issuing a kill(1) command.

Description: The program at the given path cannot be re-executed.


systemErrorString: the system error.

Cause: Examine the systemErrorString for possible causes.

Effect: None, except that the server does not start.

Action(s): Determine the cause, which could be a lack of system resources, eliminate the problem, and re-start.

Description: No basename provided for the message catalog.

Parameters: None.

Cause: A program attempted to open a message catalog but the message catalog name provided was NULL.

Effect: The event is of major severity. The effect on service is unpredictable. Logging, error, and other output may not appear in typical format.

Action(s): Rerun commands or restart servers and contact your InterMail vendor.



��'(��

��'(��

Description: An attempt is being made to change to the directory using chdir, but is failing due to the system error given.

Parameters: directory: directory being changed.

systemError: the system error from the chdir call.

Cause: Needs to be determined.

Effect: The event is of major severity. The effect on service depends on the component affected.

Action(s): Check for the existence and permissions on the directory, manually fix if necessary, and re-start.

Description: An attempt is being made to change the permissions on the file using chmod, but is failing due to the system error given.

Parameters: fileName: name of the file

systemError: the system error from the chmod call

Cause: Needs to be determined.


Action(s): Check for the existence and permissions on the directory, manually fix if necessary, and re-start.

Log Events


��'(��

��'��

Description: Failing attempt to change the ownership of a file with chown(2).


userId: the (numeric) value of the user id.

groupId: the (numeric) value of the group id.

systemErrorSTring: the system error string.

Cause: Refer to the system error for the exact cause. Most likely the error is the result of a permissions problem.

Effect: The effect on service currently is minimal. Only log files are chown().

Action(s): Check that user and group ids are correct for the configuration parameter named commonUser.

Description: The call to close with file fileDescriptor failed with system error systemerrstring. This happens when trying to close a blob file.

Parameters: fileDescriptor: the file descriptor that is failing to close

systemerrstring: the system error string.

Cause: Not foreseen.

Effect: Messages from third-party libraries (specifically Emanate SNMP) appears on stderr.

Action(s): Analyze reasons for failure.



��'��!��*��

Description: An attempt made to unlock a mutex that this thread did not lock (and possibly no thread locked.)

Parameters: mutexName: the name of the mutex.

Cause: There are no known cases where it would happen.

Effect: The event is of major to critical severity. The effect on service is unpredictable. The thread reporting this event may not continue to provide service. If it is a main thread of a server, that server may not continue to accept connections. A server logging this event is likely to display other unusual behavior.

Action(s): Restart the server. If the error recurs, you will need to find the problem and correct it. Some possibilities:

If the error appears in the MTA, it is most likely a problem with a message.

If the error involves the POP server, it is most likely a bad POP client, or else a network component, such as a router or hub.

If the error appears in the MSS, it could be due to either a message or a bad POP client, router or hub.

Log Events


��'��'(��

Description: New set of parameters received from the configuration server, but could not accommodate some of the changes.

Parameters: parmName: the name of the configuration key.

hostName: the name of host for looking up the configuration key.

programName: the name of program for looking up the configuration key.

impact: impact of the change on the program.

Cause: The program first read the config.db file for its values for all the configuration keys; then it contacted the configuration server, which had a different version of the parameters and instructed the program to install the different version. However, the program had already acted upon some of these parameters and could not accommodate the changes without restarting.

Note: This could also occur when a server is re-connecting to the configuration server.

Effect: The program will continue to execute, but with the original values for the configuration keys.

Action(s): If necessary, re-run the program to get the newer version of parameters.



��)��*��!

Description: An attempt made to delete a locked mutex.


Cause: There are no known cases where it would happen.






Log Events


��)��'��

Description: An attempt to destroy the condition named conditionName failed with the system error given.



Cause: Call to cond_destroy(3T) failed with the error code given. See the man page for cond_destroy(3T).








��)��!��

��)��

Description: Destroying the mutex mutexName failed. The system error is systemErrorString.


SystemErrorString: the system error string.

Cause: Call to mutex_destroy(3T) failed. See the man page for mutex_destroy(3T).


Action(s): Restart the process. If the error recurs, you will need to find the problem and correct it. Some possibilities:




Description: A call to dup(2) failed.

Parameters: errno: the error number that is returned from the failed call to dup(2).

Cause: None.

Effect: Messages from third-party libraries appear on stderr.


Log Events


��)��

�� !��*/��

�� !��

Description: A call to dup(2) is returning an unexpected fd.

Parameters: fdExpected: the fd that is expected from the call of dup(2).

fdReturned: the fd that is returned from the call of dup(2).

Cause: None.



Description: The nesting of exception handlers has become excessive.

Parameters: None.

Cause: The depth of the exception handling stack has exceeded 10,000. This generally indicates an infinite loop.

Effect: The event is of critical severity (mostly): another error that is the true source of the problem generally accompanies this event. It is not possible to categorize the severity of this event in isolation.

Action(s): Restart the affected server and contact your InterMail vendor.

Description: A process exited with an error status.

Parameters: exitStatus: the exit status of the process.

Cause: An InterMail process exited with exitStatus.

Effect: Cannot determine the effect of this event on the system. This is usually merely a notification; however, more serious entries may precede it in the log file in the case of an untimely demise.

Action(s): None.



�� !��'��

��

Description: A sub-process exited with an error status.

Parameters: exitStatus: the exit status of the child process.

Cause: The event should not happen with the current release of InterMail, as no forking/execing occurs. Only older versions of the InterMail software can generate this event.

Effect: The effect of this event on the system can not be determined. Treat as a critical alarm.

Action(s): Restart the process affected and contact your InterMail vendor.

Description: One of the following UNIX signals received by the process:

SIGILL: Illegal instruction (not reset when caught).

SIGABRT: Compatibility (same as SIGIOT)

SIGEMT: EMT instruction.

SIGFPE: Floating point exception.

SIGBUS: Bus error.

SIGSEGV: Segmentation violation.

SIGSYS: Bad argument to system call.

Parameters: signalName: the name of the UNIX signal received.

Cause:

Effect: The event sometimes appears along with another event indicating the processing that was going on at the time. The severity of this event depends on what thread received the signal and the processing that it was doing at the time. The event can range in severity from critical to warning.

Action(s): Restart the process if necessary. Contact your InterMail vendor.

Log Events


��(��

��1��

Description: An attempt to change the ownership of a file with fchown(2) failed.


userId: the (numeric) value of the user id.

groupId: the (numeric) value of the group id.


Cause: Refer to the system error for the exact cause. The event is probably the result of a permissions problem.

Effect: The event is of warning severity. The effect on service currently is minimal. The only files that you fchown() are log files.

Action(s): Check that user and group ids are correct for the configuration key named commonUser.

Description: The system call to retrieve a group name failed. The systemError string provides details on the cause.

Parameters: groupName: the name of the group to look up.

systemError: the system error string describing the error.

Cause: This is either a programming or configuration error.

Effect: The event could result in servers failing to communicate or users unable to either receive or download their mail. The event is of major, or possibly critical severity, if it affects all connections.

Action(s): Validate that the user and group information on the hosts is identical and restart the servers.



��1��

��1��

��1��$(��

Description: An attempt to get password file information about the user failed.

Parameters: userName: the user name


Cause: A call to getpwnam_r(3C) failed with the system error given. This could be from a programming or system configuration issue.

Effect: The event may affect entire servers or individual mailboxes, so the event may be of major or critical severity, if no servers can communicate.

Action(s): Verify that the user information on each of the hosts is identical.

Description: An attempt to get the password file information about the user with a user id failed.

Parameters: userName: the UNIX user name.


Cause: A call to getpwuid_r(3C) failed. The system error string should provide the reason for this failure.

Effect: The event is of critical severity. It can cause servers to fail to connect.

Action(s): Verify that the password information is the same on all the hosts running InterMail.

Description: An attempt to determine the thread’s priority failed.

Parameters: threadName: the name of the thread.


Cause: A call to thr_getpriority(3T) failed with the system error given.

Effect: The event is of major to critical severity. The effect on service is unpredictable. It is likely that the process is not able to continue providing service.

Action(s): Restart the server. Contact your InterMail vendor.

Log Events


��1��$(��

��'��

Description: An attempt to get per-thread data failed. This will result in the thread exiting without performing the task it assigned. This may result in problems delivering or retrieving mail.


Cause: The call to thr_getspecific(3T) failed.

Effect: The event is of major to critical severity. The effect on service is unpredictable. The server experiencing this event may behave erratically.

Action(s): Restart the server and contact your InterMail vendor.

Description: An attempt to initialize a condition has failed. This is one of several multi-threading synchronization techniques used.



Cause: A call to cond_init(3C) failed with the system error given. This is probably a problem with the system programming library.

Effect: The event is of major to critical severity. A condition variable that the process needs is not available. The results of this are not predictable. The server will not perform as expected.




��!��

��L��$(��

Description: An attempt to initialize a mutex has failed. This is one of several multi-threading synchronization techniques used.



Cause: A call to mutex_init(3T) to initialize the condition name conditionName has failed with the system error given. This is probably a problem with the system programming library.

Effect: The event is of major to critical severity. A mutex that the process needs is not available. The results of this are not predictable. The server will not perform as expected.


Description: A call to thr_join(3T) failed with the given system error string. This event cannot happen in the current revision of InterMail.



Cause: This can only be the result of a programming error, since there are no calls to thr_join(3T).

Effect: The effects on service are not predictable. The server displaying this event do not behave as expected. The event is of major or critical severity.

Action(s): The restart the server and contact your InterMail vendor.

Log Events


��$(��

��(&��

��*,�7/��

Description: An attempt to send a signal to this thread failed.

Parameters: threadName: could not signal the name of the thread.


Cause: A call to thr_kill(3T) returned the error code given.

Effect: The effect on service is unpredictable. This is a major or critical error. It is likely that there is another thread waiting on the condition, which may never resume execution.


Description: Notification written to the log file as soon as an InterMail program initializes and is “ready to provide service”. It logs the name of the user that is running the server, which is usually commonUser.

Parameters: user: the user name of the process that is running the server.

Cause: Server start up will cause this event. It is not an error.


Action(s): None.

Description: In order to prevent deadlocks in the system, locks must be set in prescribed orders. This event states the locks are not following the ordering convention.


listOfMutexes: a list of higher-priority mutexes already locked.

Cause:

Effect: The event is of major to critical severity. The effects on service are not predictable.




��*��!��

��$��

��!+��*��

Description: Locking the mutex mutexName failed. The system error is systemErrorString.

Parameters: mutexName: the mutex name.

systemErrorString: the system error information.

Cause:

Effect: The event is of major to critical severity. The effects on service are unpredictable.


Description: Attempt made to utilize more than one thread, but this program not built to support multi-threading.

Parameters: None.

Cause: Program compiled without the necessary support for multi-threading.

Effect: The effects on service are unpredictable. This is a critical error.


Description: Attempt made by thread threadName to unlock the mutex named mutexName, but that mutex not locked to begin with.


threadName: the name of the thread.

Cause:

Effect: The event is of major to critical severity. The effect on service of this event is unpredictable.


Log Events


��'"��

��*

��&��)��

Description: When an unexpected event occurs, raises an exception to handle the condition. In this case, an exception raised but there were no exception handlers to catch it.

Parameters: None.

Cause:

Effect: The event causes a program to exit. The event is of major or critical severity, depending on the server affected.


Description: An attempt made to call a function in the InterMail library without initializing the library.

Parameters: serviceEntryName: name of the service entry.

Cause:



Description: The server is not changing to its runDir directory.

Parameters: None.

Cause: • If no runDir is specified in the server’s configuration database, the message is of severity warning to indicate this fact.

• If a runDir is specified in the server’s configuration database, and there are problems creating the directory, changing its ownership or permissions, this is fatal and a log entry precedes it showing the exact nature of the problem.

Effect: Depends on the severity, because if it is fatal, the server does not run.

Action(s): Check for existence, ownership, and permissions of the directories.



��!

��'��

��&��

Description: Attempt made to lock a null mutex.

Parameters: None.

Cause: An attempt made to lock a mutex but the handle to the mutex was NULL.

Effect: The event is of major to critical severity. The effect on service is unpredictable.


Description: A call to pipe(2) is failing.

Parameters: systemError: the system error that occurs after the call to pipe(2)fails.

Cause: None.



Description: An internal programming problem occurred during shutdown.

Parameters: threadName: name of the pool manager thread.

numOfResources: the number of resources that not returned.

Cause: The thread indicated was managing a pool of resources. At shutdown time, some of the resources not returned to the pool. This is simply a bad programming practice, but could result in system resources, such as database connections, etc. not being released.

Effect: Effects on service are probably minimal, but in the case of non-returned resources, this could have a cumulative effect.


Log Events


��&��

��&�,�7��*��

��&� !��

Description: The process to kill was not running.

Parameters: processName: the name of the process program.

pid: the process id.

Cause: The process whose pid was in the server’s pid file is not currently running, and thus cannot be killed.

Effect: None, except that the process not killed.

Action(s): The server exited as the result of some other cause, so you do not need to kill it anymore.

Description: Attempt to reacquire the lock for mutex mutexName failed.



Cause: This only happens on platforms that do not properly support mutex locking while waiting on a condition. InterMail does not currently run on any such platform.



Description: The program at the given path is re-executing.


Cause: The program is re-executing so that it can generate core files for serious errors.

Effect: None. This is a notification.

Action(s): None.



��.��

��'��

Description: The call to semget to get the semaphore id failed. The path to the key file is keyPath.

Parameters: keyPath: the path to the key.

Cause:

Effect: This event has severity major in the context of one of the servers. The server that logs this event will not be able to run.


Description: The call to semget to create semaphore semaphoreName failed with system error systemErrorString.

Parameters: semaphoreName: the name of the semaphore.


Cause:



Log Events


��1��

��

Description: The call to semctl to set status of semaphore semaphoreName is failing with system error systemErrorString.



Cause: Process does not have appropriate permission, system resources are exhausted or there is a programming error

Effect: This event has severity major in the context of one of the servers. It has severity warning in the context of metl. The server that logs this event cannot run.

Action(s): Verify the process login this event was started as the correct user to insure that it had the permissions to perform the semctl call. If the system memory is exhausted or if this looks like a programming error, work with your InterMail vendor.

Description: When attempting to initialize a semaphore no name given.

Parameters: None.

Cause:

Effect: This event has severity critical in the context of one of the servers. The server that logs this event will not be able to run.

Action(s): Call your InterMail vendor.



��

��-��0��

Description: The call to semop to signal semaphore semaphoreName failed with system error systemErrorString.



Cause: The process does not have appropriate permissions.


Action(s): Verify that the process logging this event started with the correct user to insure that the process has the appropriate permissions.

Description: An attempt made to use an uninitialized semaphore. A call to semctl does this.

Parameters: None.

Cause: The process does not have the required permissions. Or, system resources exhausted.


Action(s): Verify that the process logging this event started with the correct user to insure that the process has the appropriate permissions to perform the semctl call. If system memory is exhausted, work with your InterMail vendor to free allocated blocks.

Log Events


��+��

��

Description: The call to semop to wait on semaphore semaphoreName failed with system error systemErrorString.



Cause: The process does not have appropriate permissions.


Action(s): Verify that the process logging this event started with the correct user to insure that the process has the appropriate permissions.

Description: An attempt to set the group id of the process failed with the system error given.

Parameters: groupId: the (numeric) group id.


Cause: A call to setgid(2) failed with the system error given. This is likely due to a configuration problem with InterMail.

Effect: The event is of major severity. This event may cause components in the system not to gain access to resources with the proper identity.

Action(s): Validate the user and group information for the InterMail installation.



��!��(��

��$(��

��$(��

Description: Could not increase the number of threads.

Parameters: None.

Cause:


Action(s): This event indicates that the number of threads defined by the configuration key maxThreads could not be created because the hardware either cannot support that many threads or the OS is not configured to support that many threads. Either lower the number of threads to create or reconfigure the OS to handle more threads.

Description: A call to thr_setpriority(3T) failed with the system error given.



Cause:

Effect: The event is of major to critical severity level. The effect on service of this event is unpredictable.


Description: When creating a thread an error occurs when setting thread-specific data.



Cause: A call to thr_setspecific(3T) failed with the system error given.



Log Events


��$(��'��

��

Description: A call to cap_set_proc(3C) failed with the system error given.

Parameters: capablilty: The name of the capablility attribute being set using the system call cap_set_proc().

errno: The error return by cap_set_proc().

Cause: This is a system configuration error. (SGI/IRIX only)

Effect: The effect on service of this error is unpredictable. This error should be concidered major or critical.

Action(s): See the man pages on cap_set_proc(3C), capabilities(4) and capability (4).

Use imconfdit to set /*/*/useBoundThreads: [false].

Restart the server and contact your InterMail vendor.

Description: An attempt to set the user id of the process failed with the system error code given.



Cause: Errors in the configuration of InterMail cause this.

Effect: The event is of major to critical severity. The user id of the various components of InterMail must match for the installation to behave properly. The system may defer mail and/or users may be unable to retrieve messages, depending on the components involved.

Action(s): Verify the user and group information on the hosts running InterMail.



��

��(��

Description: This is a notification that is written to the log file when the server process changes to the commonUser as specified in the config.db.

Parameters: userName: the user name which the process is assuming.

userId: the user id which the process is assuming.

Cause: Normal server operation causes this event. It is not an error.

Effect: This is an informational message.

Action(s): None.

Description: The event is of informational severity, and indicates the beginning of a graceful shutdown.

Parameters: shutdownMode: mode of shutdown requested.

Cause: imservcall has requested the server to shut down. The value of shutdownMode can be stop, drain or a number (of undefined meaning).

Effect: The effect will be for the server to shut down. If the shutdown mode is drain, then all work in progress will continue to its conclusion. If the shutdown mode is stop, then all work in progress will end in an orderly fashion at the first opportunity and clients will receive notification of the abrupt termination. When all work in progress has been finished or abandoned, the server will exit.

Action(s): None. If a drain shutdown is in progress and it seems that this will not be fast enough, you can escalate a shutdown to stop by re-invoking imservcall.

Log Events


��(��

��(��

��(��&�7��

Description: Attempt to shut down the server denied.

Parameters: currentShutdownMode: current mode of shutdown in progress.

requestedShutdownMode: mode of shutdown requested.

Cause: An attempt made using imservcall to cause the server to shut down, but a graceful shutdown mode was already in progress at that level or at a higher lever. The original shutdown will proceed uninterrupted.

Effect: None.

Action(s): None.

Description: A shutdown was already in progress for level shutdownMode, but this process abandoned when another request to shutdown at a higher level (more quickly) received.

Parameters: shutdownMode: mode of shutdown requested.

Cause: imservcall has requested the server to shut down at a higher lever than the shutdown in progress.

Effect: The effect will be for the server to shut down even more quickly.

Action(s): None.

Description: Program requested to shutdown.

Parameters: None.

Cause: Process killed with a SIGHUP and is exiting gracefully.


Action(s): None.



��(��7��

��(��

Description: This event indicates a programming error in InterMail code.



Cause: All the threads with sequence number sequenceNumber have already shut down, but there is an attempt to create a new thread with this sequence number.

Effect: Will not create the thread, but ultimate effect is unpredictable. The server will probably shut down successfully in spite of this.

Action(s): None.

Description: A significant amount of time (interval seconds) has elapsed with no reduction in the number of tasks executing on the server.

Parameters: numTasks: the number of tasks still in progress on the server.

serverName: the name of the server.

Cause: Used the program imservcall to request a server to shutdown, but no progress has been made in interval.

The server is still running.

Effect: Thread not created, but the ultimate effect is unpredictable. The server will probably shut down successfully in spite of this.

Action(s): The level of shutdown will have to escalate to exit or kill.

Log Events


��'��

��

��$(��

Description: An attempt to signal the condition conditionName resulted in a system error.



Cause: A call to cond_signal(3T) returned the error code given.

Effect: The event is of major to critical severity. The effect on service is unpredictable. It is likely that there is another thread waiting on the condition that may never resume execution.


Description: Child process exited because killed with a signal.

Parameters: signalName: the name of the signal.

Cause:

Effect: The effect on service is not predictable. This is a major or critical error.


Description: An attempt to suspend a thread has failed.



Cause:

Effect: The effect on service is not predictable. This is a major or critical error.




��$(��,��)��

��$(��,��

Description: When attempting to destroy the attribute data for thread threadName encountered error systemErrorString. This was because of calling pthread_attr_destroy.



Cause:


Action(s): Using the information from systemErrorString determine the cause of this event.

Description: When creating a new per-thread data for thread threadName encountered error systemErrorString. This was because of calling pthread_attr_init.



Cause: Memory exhausted or programming error.


Action(s): Determine if the host that this server is running on is okay and that the system resources are not exhausted. If this is the case or it is due to a programming error contact your InterMail vendor.

Log Events


��$(��'��

��$(��'��

Description: When creating a new per-thread data key for thread threadName an error encountered.



Cause: A call to thr_keycreate(3T) has failed with the error code given.

Effect: The event is of major to critical severity. This is an important operation for multi-threaded applications. This failure will cause the thread creation to fail. The effect on service is unpredictable.


Description: A subclass of thread failed to implement a threadmain() member function.

Parameters: None.

Cause: All subclasses of thread must implement a threadmain() function which will be the main function of the thread. Some class has failed to do this.

Effect: The event is of major to critical severity. The effect on the service is unpredictable. The thread that is unable to execute threadmain() will not run and its work will not be done.




��$(��(��

��$(��*��0�

Description: When attempting to get the schedule policy and schedule parameters for thread threadName the system error systemErrorString occurred. The system call was pthread_getschedparam.



Cause:


Action(s): Using the information from systemErrorString determine the cause of this event.

Description: When setting the size of the stack for a new thread threadName an error encountered systemErrorString. This was because of calling pthread_attr_setstacksize.

Parameters: stackSize: the stack size.

threadName: the name of the thread.


Cause: Memory exhausted or stack size exceeds system limit.


Action(s): • Determine if the host that this server is running on is okay and that the system resources are not exhausted.

• Verify the server has started with the correct user.

• If these two cases are not true, this is likely to be a programming error, contact your InterMail vendor.

Log Events


��$��

��-��(�'�� !��

��-��*��!��

Description: While exiting, a process encountered too many fatal errors to cleanly shutdown. It will exit.

Parameters: None.

Cause: This may be because of operating system instability or hardware errors.

Effect: The event should have little effect on the service if encountered while shutting down the server. At other times, it is a major or critical error.

Action(s): If this occurred while shutting down, check the other fatal InterMail errors reported. Otherwise, restart the server and contact your InterMail vendor.

Description: A C++ exception that was not caught in the code was raised. InterMail does not raise or catch C++ exceptions.

Parameters: exceptionName: The name of the exception.

Cause: Either a system library or third-party library has raised a C++ exception.

Effect: The event is of major or critical severity, and may disrupt service.


Description: An attempt to unlock a mutex has failed with the system error given.



Cause: A call to mutex_unlock(3T) has failed with system error.

Effect: The event is of major to critical severity. The effect on the service is unpredictable.




��+��/�'��

��+��$��

Description: An attempt to wait on a condition has failed with the system error given.



Cause: A call to cond_wait(3T) has failed with a system error.

Effect: The event is of major to critical severity. The effect on service is not predictable. The server reporting this event does not continue to provide service reliably.


Description: A non-InterMail library is writing a line to stderr. Normally, servers do not write to stderr unless explicitly instructed to with the –wantToConsole option, or while tracing in debuggable code.

Parameters: message: the message that is written to stderr.

Cause: Third-party libraries write to the UNIX stderr file handle.

Effect: Depends on the message.


Log Events


RME Log Events

&��.��'��&��

&��.��)��'��(�"��

Description: An object reference from a remote client was invalid.

Parameters: None.

Cause: Possibly a client error or network error.

Effect: The event is of major severity. The effect on service depends on the object that caused the alarm. This alarm usually affects a single user. However, if it floods, it could affect the entire MSS process.

Action(s): Reboot the server experiencing the error if the alarm is repeating several times a minute. Check for other InterMail or network errors. If the problem does not clear, contact your InterMail vendor.

Description: The configuration key dirCacheHost was indecipherable, using “localhost”. The value was configLocalHost.

Parameters: configLocalHost: the configuration entry for the local host.

Cause: The ISD is not responding. The process could have terminated unexpectedly, or may have an incorrect configuration.

Effect: The effect on service for this event is warning. The ISD will run using the default local host. If this is okay, additional event will occur and there will be no effect on service.

Action(s): Investigate if the configuration information is out of date or corrupted.



&��.��/��

&��'��$��

&��'��$��A

Description: A fixed-length buffer for imdirserv information has overrun. The length of the buffer is maxLength, and the length of the string is stringLength.

Parameters: maxLength: the maximum length of the buffer.

stringLength: the length of the string to store.

Cause:



Description: While waiting for a response for an RME operation, the operation timed out.

Parameters: host name: the host name of the machine.

Cause: The host machine could have restarted or processes on that machine could have restarted. This could indicate a heavily loaded system.

Effect: The event is of minor severity. Likely to affect a single user or subset of users only.

Action(s): Check the status of the host machine. If the error is repeating several times a minute, check network status.

Description: While waiting for a response for an RME operation, the operation timed out.

Parameters: server name: the name of the server.




Log Events


&��'��-��

&��)��'��(�)��

&��)��'��(��

Description: The RME connections for retrieving mail from MSS mssHost are limited (see the configuration key maxMSSRetrieveConnectionList) and we could not obtain an RME connection within the timeout specified by the configuration key maxMSSRetrieveConnectionTimeout.

Parameters: mssHost: The mss host we were trying to connect to.

Cause: The MSS specified is very busy, running slowly, or the limit for that host in the maxMSSRetrieveConnectionList configuration key is too low.

Effect: The client trying to retrieve mail thinks that the mail services are currently unavailable. It effects only that single client.

Action(s): • Look at the performance of the MSS and the number of connections to it.

• Look at the maxMSSRetrieveConnection.

Description: The Directory Server is down.

Parameters: hostname: name of host that is down.

Cause: The host machine is restarting or processes on that machine are restarting. This indicates a heavily loaded system.

Effect: The event is of minor severity. Likely to affect a single user or subset of users.


Description: The Directory Server on hostname is up. This is not an error but an informational message.

Parameters: hostname: name of host that is up.

Cause: Not applicable.

Effect: No effect on service. This is an informational message.

Action(s): None.



&��

&��"��

&��)��

Description: An error occurred while filling the RME buffer.

Parameters: None.

Cause: Probably a network error.

Effect: The event is of minor severity. Likely to affect a single user only.

Action(s): If the error is repeating several times a minute, check network status and consider restarting InterMail servers.

Description: Attempt made to attach to a server with an RME socket, but no host specified.

Parameters: portname: the name of the port.

Cause: If the port name does not make sense, the problem could be memory corruption.

Effect: The event is of minor severity. Likely to affect a single user only. However, if it floods, it will affect the entire server.

Action(s): If the port name seems reasonable and the error is repeating, restart the InterMail server. If error continues, contact your InterMail vendor.

Description: The destination for an RME operation is null.

Parameters: None.

Cause: This could happen if the network connection between the machine requesting the RME operation and the machine serving the RME operation is down, or if the server requesting the operation is no longer running.

Effect: The event is of minor severity. This is likely to affect just a single user; but if it floods, it probably means that a server crashed.

Action(s): Verify that the network between the RME requester and RME requestee is up. Verify that expected servers are up and running.

Log Events


&��/��

Description: Program logging this entry requested to perform an RME operation that it does not support.

Parameters: myProtocolLevel: the protocol level of this program.

itsProtocolLevel: the protocol level of the other program.

objectIAm: the RME object that does not support the operation.

operationName: the name of the operation.

Cause: One of the following may have happened:

Program copied to the installation instead installing package (which would have insured that all executables were at the same protocol level).

A program is communicating with a peer on another host that is at a lower protocol level.

Random memory corruption. (This is the least likely scenario.)

Effect: The event is of minor severity. At infrequent rates, it is likely affecting single message stores only. If repeating several times a minute, many users of a server are probably affected.

Action(s): Check the release notes for compatibility issues. Upgrade the software or re-install as required. pkginfo -l Intermail will tell you the version number of the installed package on any host. If versions seem correct and error is repeating at a high rate, restart the InterMail servers and check for other InterMail and system errors. If error continues, contact your InterMail vendor.



&��.��)��

&��.��(

Description: During an RME operation a protocol error occurred. This could be because there are incompatible versions of clients at either end of the connection or if the data passed is corrupt.

Parameters: None.

Cause: This event could be caused by:

• Wrong data format (which could be a result of incompatible clients at either end of a connection).

• Non null terminated string passed to an RME routine.

Effect: The event is of minor severity. However, if error floods, many users may be affected.

Action(s): Verify that the InterMail installation done correctly. pkginfo -l Intermail will tell you the version number of the installed package on any host. Check the release notes for compatibility issues. Upgrade the software or re-install as required.

Description: RME detected that the size of a collection transmitted through the network or persistent object file is incorrect.

Parameters: collection size: the size of the collection to send.

max collection size: the maximum size for a collection sent.

Cause: Some other problem, such as memory corruption or an unreliable network, is usually the reason for this type of failure.

Effect: The event is of minor severity if it happens occasionally, affecting only a specific message store. If the error floods, it will affect all users of the server.

Action(s): Look in logs for other events indicating memory corruption or network problems. If the error is repeating, restart InterMail servers. If error continues, contact your InterMail vendor.

Log Events


&��

&��(

Description: A protocol error occurred, possibly because of incompatible versions of InterMail at either end of a connection.

Parameters: None.

Cause: • An improperly done installation of InterMail.

• Improperly configured system.

• Program copied to the installation (instead of installed by a package, which would have insured that all executables were at the same protocol level)

• Program is communicating with a peer on another host that is at a lower protocol level.

• It is possible for this event to be the result of random memory corruption, but this is much less likely.


Action(s): Verify that the InterMail installation done correctly. pkginfo -l Intermail will tell you the version number of the installed package on any host. Check the release notes for compatibility issues. Upgrade the software or re-install as required.

Description: The program logging this entry has a different protocol level than that of the program requesting the RME operation.

Parameters: myProtocolLevel: the protocol level of this program.

itsProtocolLevel: the protocol level of the other program.

Cause: • Program copied to the installation (instead of installed by a package, which would have insured that all executables were at the same protocol level)

• Program is communicating with a peer on another host that is at a lower protocol level.


Action(s): Check the release notes for compatibility issues. Upgrade the software or re-install as required. pkginfo -l Intermail will tell you the version number of the installed package on any host.



&��'��*��

&��&��

Description: In imservcall, while waiting for the server to respond with the number of tasks currently executing, the socket was unexpectedly closed by the server.

Parameters: serverName: the name of the server.

Cause: The server terminated unexpectedly while attempting to shut down gracefully.


Action(s): Check the log file for indications of other problems that may have possibly caused this.

Description: Attempted to perform an RME on an object (such as a folder or message) that is missing.

Parameters: None.

Cause: This may be the result of another user accessing the same (shared) message store, and the client not updating its state correctly. This could be due to corrupted memory.


Action(s): None if the error is only occasional. If the error is repeating every few minutes, restart InterMail servers. If error continues, contact your InterMail vendor.

Log Events


&��-��+��(�.��

&��-��!��&��

Description: Attempt made to unbind a client from the RME object where the client was not bound to the RME object.

Parameters: None.

Cause: This could be a client error.

Effect: The event is of warning severity. No effect on a user unless the error is flooding.

Action(s): None if error is occasional. If error occurs at a rate of several per minute, check for other InterMail errors and consider restarting InterMail servers. If error continues, contact your InterMail vendor.

Description: When waiting for a reply on synchronous RME call, the input manager on host name returned unexpectedly with return value.

Parameters: return value: the return value from the input manager.

host name: the host name.



Action(s): Check the status of the host machine. If the error is repeating several times a minute, check the network status.



&��-��!��&��A

Remote Control Server Log Events

&��.�� !��

&��'(��

Description: When waiting for a reply on synchronous RME call from serverName the input manager returned unexpectedly with return value.

Parameters: return value: the return value from the input manager.

serverName: the server name.



Action(s): Check the status of the host machine. If error is repeating several times a minute, check the network status.

Description: The call to imservctrl failed with the exit status given.

Parameters: exitStatus: the child process’s exit status.

Cause:

Effect: Actions requested of immgrserv not carried out.


Description: A call to fstat(2) failed.

Parameters: systemError: the system error after the failed call to fstat(2).

Cause:

Effect: The output from the child process may be lost.


Log Events


&��'��$��

&��'��%��

&��)��)��

Description: Shows the exact command-line invocation of imctrl.

Parameters: invocation: the exact command line invocation of imctrl.

Cause:

Effect: None.

Action(s): None.

Description: The command line contains verbs that are contradictory for the same server.

Parameters: oneVerb: one of the verbs in conflict.

otherVerb: the other of the verbs in conflict.

server: the server with contradictory verbs

host: the host of the server with contradictory verbs

Cause: Two contradictory verbs have specified the same server on the same host. Correct the contradiction and re-issue the command.

Effect: Servers not affected.

Action(s): Correct the contradiction and re-issue the command.

Description: The call to imservctrl should have terminated the immgrserv process, but after secondsWaited seconds, immgrserv was still alive.

Parameters: secondsWaited: the number of seconds waited for by immgrserv after having instructed imservctrl to kill it (immgrserv).

outputOfImservctrl: the stdout and stderr output of imservctrl.

Cause:

Effect: The immgrserv process will exit, since it has shutdown to a point, having expected its own imminent demise, that it cannot continue. This means imctrl will not be able to control servers on this host until immgrserv is re-started locally.




&��)��

&��)��

&�� !��

Description: A call to dup(2) failed.

Parameters: expectedFd: the fd the call expected to return.

systemError: the system error after the failed call to dup(2)�

Cause:



Description: A call to dup(2) return an unexpected fd.

Parameters: fdExpected: the fd expected from the call of dup(2).

fdReturned: the fd returned from the call of dup(2).

Cause: None.

Effect: The actions requested of immgrserv cannot be carried out.


Description: A call to exec(2) failed.

Parameters: systemError: the system error after the failed call to exec(2).

Cause:



Log Events


&��*��

&��"��

&��'��

Description: A call to fork1(2) failed.

Parameters: systemError: the system error after the failed call to fork1(2)

Cause:



Description: The Remote Control server (immgrserv) received an incoming request from an illegal host.

Parameters: hostname: the host name of the machine where imctrl invoked.

Cause: The configuration key legalHosts is either not “all” or does not include the hostname mentioned. Therefore, this host not allowed to communicate with immgrserv.

Effect: Critical: the imctrl application will not run.

Action(s): Change to a host allowed by the legalHosts parameter, or change the parameter.

Description: A call to pipe failed.

Parameters: systemError: the system error after the failed call to pipe(2).

Cause:





&��

&��&� ��

&��&� ��

Description: The call to imservctrl terminated due to a signal.

Parameters: signalNumber: the signal number that terminated the child process.

signalText: the text description of the signal that terminated the child process.

Cause:



Description: The RME command failed.

Parameters: RME: the RME it is performing.

Cause: Preceding log entries will indicate the exact nature of the failure.

Effect: Desired actions not performed on the remote servers.

Action(s): Correct the problem and try again.

Description: The RME command succeeded.


Cause:

Effect: None.

Action(s): None.

Log Events


&��&�

&��+��$��

&��*�� !��

Description: Starting an RME command.


Cause:

Effect: None. The event is of informational severity.

Action(s): None.

Description: A call to waitpid(2) was still not successful after a reasonable number of seconds.

Parameters: secondsWaited: the number of seconds waited for the child to finish.

Cause:



Description: Indicates an attempt to “POP” a locked mailbox (message store).

Parameters: None.

Cause: A user successfully authenticated a POP3 session using the POP USER and PASS commands, but the message store exclusively locked by some other POP session.

Effect: There is no adverse effect on service. The user attempting to “POP” a locked message store receives an error response.

Action(s): This event expected during the normal course of operation, and no action is usually necessary.

If users locked out of their mailboxes often, consider setting the popLockTimeout configuration key to a lower value.



SMTP Log Events

��,��!��

��.��&��

Description: An SMTP client sent a command to the server that contained an improper e-mail address. The address fixed to conform to e-mail standards.

Parameters: otherHost: the other SMTP host.

SMTPCommand: the SMTP command given by the other host.

newAddress: the new address.

Cause: The connected SMTP client does not follow Internet standards, or is perhaps misconfigured.


Action(s): No action is necessary. Contacting the remote site’s postmaster may be a good idea if the improper addresses are excessively broken. It is possible that the resulting address will not refer to an actual mailbox, so delivery to it may fail.

Description: The anti-spam relay policy is mis-configured because it is not a known policy.

Parameters: relay policy: The relay policy as listed in config.db.

Cause: The config.db entry for relaySourcePolicy is incorrectly entered.

Effect: The relaySourcePolicy defaults to allow-all.

Action(s): Fix the config.db entry for relaySourcePolicy.

Log Events


��'��1��&��

��'��$��

Description: The SMTP server on the named host sent a greeting message containing a status code that indicates it is unwilling or unable to accept mail.

Parameters: hostName: the host name.

statusCode: the status code.

greetingType: the greeting type.

Cause: The remote server is unwilling or unable to accept mail.

Effect: The event is of informational severity. Mail not delivered to the named machine, so this condition may be causing mail to queue locally (it may deliver successfully to another mail server, though).

Action(s): Connect to the SMTP port of the machine referenced in the hostName key (using telnet) to see the greeting message.

Description: The connected SMTP client sends a line that exceeds the defined maximum line length.

Parameters: clientIp: the IP address of the client.

clientLineLengthLimit: the defined maximum line length allowed from a client.

Cause: Either the client program does not correctly implement the SMTP protocol, someone has connected to the SMTP port with telnet and issued an invalid command, or the configuration variable clientLineLengthLimit is set too low.

Effect: The client command is rejected.

Action(s): Inspect the clientLineLengthLimit configuration variable. Make sure it is 0 (no limit) or at least 1000 (the RFC821 maximum).



��'��)��

��'��1��

Description: While attempting to deliver a message to the specified domain, the system determined (by DNS lookups) that the message would have to be delivered locally; however, the mail server is not properly configured to accept mail for the domain. If the message were delivered to the server, it would end up in a loop whereby the message continually delivers to itself.

Parameters: mailRecipient: the recipient of this message.

Cause: • The MX records for the domain indicate that there are no other servers with a higher preference than this server

• Upon connecting to the remote server, it had the same name as this server (so the server probably connected to itself to deliver the mail).

Effect: The event is of informational severity. While this condition exists, cannot deliver mail destined for the domain.

Action(s): Look up the MX records for the domain (using nslookup). Check the MTA configuration for the list of local mail domains. Fix the configuration of the MTA to accept mail for the domain and/or fix the configuration of the DNS for the domain.

Description: The SMTP server running on hostName did not respond with a greeting within a reasonable amount of time, so the connection closed.

Parameters: hostName: the name of the host.

Cause: The server is likely busy handling other network connections and does not have the resources to respond within the time-out period. A network connectivity problem may also be the cause, but this is less likely.

Effect: The event is of informational severity. Mail to deliver to the server may have queued for a later attempt; however, it may have successfully delivered to an alternate mail server. If this condition persists for several days and no other servers are available to receive the messages, they will return to their senders.

Action(s): • Use trace route to verify network connectivity.

• telnet to the remote host’s MTA port.

Log Events


��'��&��

��'��&��

Description: The SMTP server running hostName did not respond to the specified command within a reasonable amount of time, so the connection closed.

Parameters: hostName: the host on which the other server is running.

command: the command the other server did not respond to.

Cause: The server is likely busy handling other network connections and did not have the resources needed to respond within the time-out period. A network connectivity problem may also be to blame.


Action(s): Mail to deliver to the server may have queued for a later attempt; however, it may have successfully delivered to an alternate mail server. If this condition persists for several days and no other servers are available to receive the messages, they will return to their senders.

Description: The SMTP server on hostName responded to an SMTP command with the reply code indicated. Reply codes in the 400 range indicate a temporary failure and those in the 500 range are for permanent errors.

Parameters: hostName the host on which the other server is running.

response: the response of the other server.

command: the command issued to the other server.

Cause: The cause depends on the command issued and the conditions on the particular server and its configuration. Many of the possible failures and errors are normal and are no cause for alarm. However, they will show why a particular site is not able to receive mail, or why a particular message bounced or queued for a later delivery attempt.


Action(s): Check the logs for subsequent SmtpMessageDeferred or SmtpMessageDelivered entries to see which message affected.



��'��'��

��'��)��

Description: Summary of resources that a disconnected SMTP client just used. The parameters indicate the length of time the client connected to the server, how many messages it sent during that time, and the total number of bytes it sent to the server during the connection.

Parameters: client: the client’s name.

time: the number of seconds after connect time.

numMessages: the number of messages the client sent.

numBytes: the number of bytes the client sent.

Cause: This event logged whenever a connection is closed.


May indicate that a client is attempting to deny service to other users of the system if SMTP clients are connected for long periods of time send many bytes to the server without sending many messages

Action(s): NA.

Description: A connection dropped.

Parameters: None.

Cause: When this warning occurs, it indicates that the dropConnections configuration key is on, meaning that all connections made to this host will drop.


Action(s): If this is not the desired result, disable the dropConnections feature.

Log Events


��'��)��&'�$

��'��&��

Description: A connection dropped because the message sent had too many recipients.

Parameters: None.

Cause: This warning indicates that a message contained more than the maximum number of recipients, as defined in the configuration key dropMaxMessageRCPTs.


Action(s): If this behavior is correct, ignore this warning. Otherwise, modify the dropMaxMessageRCPTs configuration key appropriately.

Description: An SMTP client connected to the system.

Parameters: otherHost: the host of the client.

Cause: The event is logged whenever there is an SMTP connection to the system.


Action(s): None.



��'��$��

��)��.��'��

��)��*��

Description: An SMTP client had a long period of inactivity, so the server closed the connection.

Parameters: hostName: the host the client was connecting from.

Cause: The remote client may have crashed or otherwise stopped using the connection without properly closing it. A network outage may also cause this behavior since it would block traffic between the two sites.

Effect: None. If clients from the same or similar location repeatedly time out, it may be an indication that they are attempting to deny service to other users of the system by tying up all the available SMTP servers.

Action(s): None. This is a common occurrence, so it is usually not a cause for concern. Look for the subsequent SmtpConnectionClosed message to see if the client successfully sent any mail to the system. If it did not, then it might be an indication that there is a network problem between the two sites. Clients that repeatedly time out may actually be having trouble sending mail to the server.

Description: The domain does not have any MX records or address (A) records according to the DNS, so cannot deliver mail to it.

Parameters: domainName: the domain name.

Cause: The DNS for the named domain is misconfigured.


Action(s): Look up the MX and A records of the domain (using nslookup).

Description: A DNS lookup of the domain failed.


Cause: The local name server(s) failed to look up the domain.

Effect: The event is of informational severity. Mail destined for users at the domain will be queued for a later delivery attempt.

Action(s): Attempt to look up the domain using nslookup.

Log Events


��)��*��$��/��

��)��-�*��

��"��

Description: A DNS lookup of the domain timed out.


Cause: The local name server failed to look up the domain because the DNS servers they contacted failed to respond in a reasonable amount of time.

Effect: The event is of informational severity. Mail destined for users at the domain will be queued for a later delivery attempt.

Action(s): Attempt to look up the domain using nslookup.

Description: While attempting to deliver a message to the specified domain, the MTA was unable to determine if the domain was local or not, so message scheduled for outbound delivery.


Cause: The local domain list has an entry for the domain, but it does not correctly specify how to process it.

Effect: The event is of major severity. Mail destined for users at the domain will be queued for a later delivery attempt. If the domain is local or redirected to an alternate domain, then cannot deliver mail correctly while this condition persists.

Action(s): Check the MTA configuration for the list of local mail domains and correct any mistakes.

Description: The specified host does not exist.


Cause: MTA looked up the domain, told that it does not exist. Most likely, someone tried to send a message to someone at the domain.


Action(s): Look up the domain in the DNS (using nslookup‘).



��-��

��'��$�)��*��

Description: A message addressed to a user at a local domain, but the user name (everything before the @ in the address) contains illegal characters.


Cause: Somebody attempted to send a message to the user.

Effect: The event is of informational severity. Since this is an illegal name, the user will not be able to receive the mail.

Action(s): Ignore, or check to make sure that such a user does not actually exist.

Description: After writing the message files to the disk, the system could not guarantee data permanently stored.

Parameters: hostName: the host name of the client.

sender: the sender of the message.

messageFilename: the name of the message file.

Cause: Disk experienced an I/O error, so integrity of files not guaranteed.

Effect: The event is of critical severity. The SMTP client defers the message and tries to send it again later, so the message is not lost. However, a serious problem with the mail spool disk could cause data loss in the future.

Action(s): Check for a previous error message detailing the failure, complete with the system-reported error message. Perform diagnostics on the disk to see if it needs replacing.

Log Events


��)��*

��

Description: Could not pull a deferred message out of the queue, so could not deliver it. The MTA moves the message’s control file out of the deferred directory for the host and puts it in the control directory to begin delivery. This operation failed for the reason indicated by the system error.



Cause: The system error should indicate the cause of the failure.

Effect: The event is of major severity. Message not delivered until problem fixed.

Action(s): Remedy the problem and the MTA will automatically deliver the message the next time it processes the queue.

Description: The disk used to store messages while the mail server is handling them does not have enough space to store the message currently sent by the client.

Parameters: hostName: the name of the client’s host.

sender: the sender of the message

filename: the filename written, relative to “control” or “message”.

Cause: The mail spool disk is full.

Effect: The event is of critical severity. The SMTP client will defer the message and try to send it again later, so the message is not lost. However, cannot deliver mail through the system while this condition persists.

Action(s): Reclaim space on the disk, or replace it with a bigger one.



��$��.��

��$��

Description: The remote SMTP client attempted to deliver a message to the server, but it rejected because the message was larger than the maximum message size configuration key.

Parameters: hostName: the client’s hostname.

sender: the sender of the message.

size: the size of the message in bytes.

Cause: The client may have told the server how big the message was prior to sending it, so the server rejected it immediately. Or it may not have specified the size and, on receiving the message, the total number of bytes received was larger than the maximum.


Action(s): NA.

Description: Message addressed to a user at a local domain, but the user name (everything before the @ in the address) is longer than 64 characters.


Cause: Somebody attempted to send a message to the user.

Effect: The event is of informational severity. If someone set up their e-mail address with this user name, they will not be able to receive any mail.

Action(s): Ignore, or verify that a local user with that name does not actually exist.

Log Events


��

��#��

��&��&�4��

Description: The remote mail server contacted in order to deliver a message to it, but it indicated that it does not accept SMTP mail.

Parameters: hostName: the name of the host.

Cause: Somebody sent a message addressed to a recipient on a machine that does not receive mail through SMTP. This is probably a mistake on the sender’s part.


Action(s): Ignore, or connect to the machine with telnet to verify that it does not accept mail (it will respond with a reply code of 521).

Description: The MTA began an attempt to deliver mail to the listed domain.

Parameters: domainName: the name of the domain.

Cause: The MTA may be performing one of its regularly scheduled attempts at delivering all spooled mail, or the spool run may have started manually.


Action(s): None.

Description: Message sent from the null address, < >, not delivered to the recipient indicated because the number of recipients would have exceeded the number specified in the maxNullSenderRCPTs configuration key. Messages from the null address usually only have one recipient since they should be either bounce messages or auto-replies. A message from < > with multiple recipients is often unsolicited junk mail.

Parameters: address: the recipient of the message.

Cause: Someone sent a message without a return address to several recipients.

Effect: Message delivered only to the first maxNullSenderRCPTs recipients; the sending client will be unable to return the message to its originator (since there is no return address).

Action(s): None.



��&��

��,��

��.��*��

Description: A message has recipients rejected because they would require relaying.

Parameters: None.

Cause: The message rejected because it violated one of the relay restrictions defined in the configuration database.


Action(s): If this is not the intended behavior, modify the relay configuration keys appropriately. Otherwise, ignore this warning.

Description: An incoming message was rejected (blocked) because the sender’s address is invalid (improperly formatted).

Parameters: sender: The sender of the message.

Cause: The sender is sending mail with an improperly formatted MAIL FROM: address (such as joe@@) and the rejectSenderBadAdddress configuration key is set to true.

Effect: The message is blocked, and a 550 error code is sent to the client of the SMTP session

Action(s): Find out why the sender is invalid and fix the client sending an improper sender, or set rejectSenderBadAddress to false. Typically it is a spammer sending from an invalid MAIL FROM:.

Description: Message sent had recipients rejected because the sender blocked.

Parameters: None.

Cause: The event indicates that the configuration key blockLocalNoAcct is set and the sender of the message is a local domain that does not have an account.


Action(s): If this behavior is correct, ignore the event. Otherwise, modify the block configuration key(s) appropriately.

Log Events


��)��'��%��

��)��,��

��)��

Description: Message temporarily rejected because could not look up the domain in the sender’s address in the domain name system (DNS).

Parameters: sender: the sender of the message.

Cause: The DNS failed to determine whether the domain from the sender’s address exists or not.

Effect: The message temporarily deferred at the sending site. When the client re-attempts the delivery, the message will be accepted if the DNS can resolve the domain name. Otherwise, it will remain queued.

Action(s): None.

Description: A message rejected because the sender’s address contains an IP address for a domain (such as <user@[10.20.30.40]>).


Cause: The original mail client that submitted the message may be misconfigured, or the sender may be attempting to use the computer resources of this server to deliver unsolicited commercial e-mail (UCE, commonly known as spam).

Effect: Messages from senders with IP addresses for domains are rejected unless you set /*/mta/rejectSenderIPDomain to false.

Action(s): None.

Description: Message rejected because the sender’s address does not have a domain.


Cause: The original mail client that submitted the message may be misconfigured, or worse, the sender may be attempting to use the computer resources of this server to deliver unsolicited commercial e-mail (UCE, commonly known as spam).

Effect: Messages from senders without domains rejected.

Action(s): None.



��)��!��

��.��-��

Description: Message rejected because the sender’s address contains a domain not found in the domain name system (DNS).


Cause: The original mail client that submitted the message may be misconfigured, or worse, the sender may be attempting to use the computer resources of this server to deliver unsolicited commercial e-mail (UCE, commonly known as spam).

Effect: Messages from senders with bad domains rejected.

Action(s): None.

Description: The connected SMTP client issued a command with invalid or missing parameters.

Parameters: hostName: the name of the client’s host.

invalidCommand: the invalid command.

Cause: Either the client program does not correctly implement the SMTP protocol, or someone has connected to the SMTP port with telnet and issued an invalid command.


Action(s): Ignore.

Log Events


��'��-�*��

��

Description: The connected SMTP client issued an unrecognized command, which was ignored.


invalidCommand: the invalid command.

Cause: Either the client program does not correctly implement the SMTP protocol, or someone has connected to the SMTP port with telnet and issued an invalid command.


Action(s):

Description: The connected SMTP client (or person connected to the SMTP port with telnet) issued an ETRN command for the domain. ETRN causes the server to start delivering all queued mail for the domain.

Parameters: domainName: the client’s domain name.

domainToSend: the domain whose mail to send.

Cause:

Effect: The event is of informational severity. This is probably a harmless event, where the client simply wants the server to start delivering mail queued for the domain (presumably because it is acting on behalf of the domain). If the same site issues many unrelated ETRN requests, it may be attempting to deny service to other users whose mail will be delayed while the server attempts delivery to the domains.

Action(s):



�� !��

��"��*��,��

Description: The connected SMTP client (or person connected to the SMTP port with telnet) issued an EXPN command for the address. EXPN returns information that indicates if the address is valid.

Parameters: domainName: the name of the client’s domain.

Address: the name that the client attempted to expand.

Cause: NA.

Effect: The event is of informational severity. This is probably a harmless event, but may indicate an attempt to determine a valid user id on the system for a later attempt at breaching system security (by some means other than through the mail system). If many unrelated EXPN commands issue from the same site, it may be an indication that the connected user has bad intentions.

Action(s): Ignore.

Description: The connected SMTP client (or person connected to the SMTP port with telnet) issued an SMTP command that known to cause security breaches in other MTAs. The command ignored.


command: the command attempted.

Cause: Somebody is searching for vulnerabilities in the MTA based on known problems with other MTAs. (DEBUG and WIZ are two commands that allowed ordinary users to breach security of systems running early versions of sendmail.)

Effect: The event is of warning severity. May indicate an attempt to breach security of the MTA. The intentions of the client may be malicious, or they could just be checking for known problems that they intend to report and/or fix.

Action(s): Ignore.

Log Events


��#��

��&��/��

Description: The connected SMTP client (or person connected to the SMTP port with telnet) issued a QSND command for the domain. QSND causes the server to start delivering all queued mail for the domain.


domainToSend: the domain whose mail to send.

Cause: NA.

Effect: The event is of informational severity. This is probably a harmless event, where the client simply wants the server to start delivering mail queued for the domain (presumably because it is acting on behalf of the domain). If the same site issues many unrelated QSND requests, it may be attempting to deny service to other users whose mail will be delayed while the server attempts delivery to the domains.

Action(s): You can turn off the QSND command by modifying /*/mta/allowQSND.

Description: The SMTP server responding to an SMTP command sends a line that exceeds the given maximums.

Parameters: serverIp: the IP address of the offending server.

serverLineLengthLimit: the maximum number of characters per line that is allowed in an SMTP server response.

serverTotalLinesLimit: the maximum number of total lines that is allowed in an SMTP server response.

Cause: Either the server program does not correctly implement the SMTP protocol, or the configuration variables have been set with limits that are too restrictive.

Effect: Outgoing message deferred locally.

Action(s): Adjust the configuration variable, Ignore.



��$��.��'��

��%��

Description: The SMTP client issued too many invalid commands, so the connection closed.


Cause: Either the client program does not correctly implement the SMTP protocol, or someone has connected to the SMTP port with telnet and issued several invalid commands.


Action(s): Ignore, or look for previously logged events for SmtpServerBadUsage and SmtpServerCommandUnknown to see what the bad commands were.

Description: The connected SMTP client (or person connected to the SMTP port with telnet) issued a VRFY command for the address. VRFY returns information that indicates if the address is valid.


address: the address to verify.

Cause: This is probably a harmless event, but may indicate an attempt to determine a valid user id on the system for a later attempt at breaching system security (by some means other than through the mail system). If many unrelated VRFY commands issue from the same site, it may be an indication that the connected user has bad intentions.


Action(s): You can turn off the VRFY command by modifying the /*/mta/allowVrfy configuration key.

Log Events


��!&'�$� !��

��'��'��$��,��

Description: Message moved to the sidelined directory because addressed to more than max_rcpts.

Parameters: message id: the value of the Message-ID header.

num_rcpts: the total number of recipients.

max_rcpts: the number of recipients per connection that does not trigger sidelining.

Cause: Someone sent a message to num_rcpts recipients.

Effect: The message has moved to an area where it will remain indefinitely. Message delayed until manually resubmitted to the MTA.

Action(s): Inspect the message to determine if whether to deliver it. Use immsgprocess to resubmit it if desired; otherwise delete the header, body, and control files.

Description: The Emanate library code cannot connect to the master SNMP agent.

Parameters: None.

Cause: None.

Effect: The server is unable to report SNMP traps or handle requests.

Action(s): If the snmpdm server crashes or is not started, this eliminates the problem.

If it is not your intention not to use SNMP at your site, answer the appropriate questions to this effect in the installation process. This sets the _opt configuration parameters to -nosnmp in addition to any other appropriate options. If this has been subsequently undermined, you may need to restore these configuration parameters to their original post-install values, or at least to -nosnmp.



��

��,��

SSL Log Events

��'��

Description: The call to InitSubAgent() in the Emanate library failed.

Parameters: None.

Cause: None.

Effect: The particular server runs, but is not SNMP-enabled.


Description: The particular server runs, but is not SNMP-enabled.

Parameters: masterAgentHostName: the name of the host on which the master SNMP agent runs.

systemError: the system error from the gethostbyname() call.

Cause: None.

Effect: The particular server runs, but is not SNMP-enabled.

Action(s): The masterAgentHost configuration parameter should have been set correctly in the installation process, but if the host name is incorrect or non-existent, change the parameter in config.db.

Description: An error occurred during the SSL configuration phase, at server startup.

Parameters: sslErrorString: a descriptive character string derived from the code defined by SSLPLUS, indicating the error condition.

Cause: Cannot configure SSL properly due to various configuration errors indicated by the error string.

Effect: The event is of critical severity for SSL functionality. This event has no effect on the server’s non-SSL operations.

Action(s): Examine the error string, and act accordingly.

Log Events


��).��

��"��(�*�

Description: An error occurred during session cache database initialization.

Parameters: None.

Cause: This event happens when the server is trying to write/read the session cache data to/from a file, which can only happen when the server is initializing the session cache. The session information only resides in a data file when the application built with the SSLDEBUG flag.

Effect: The event is of critical severity (for SSL operation, but no effect on non-SSL operations).

Action(s): There is a log entry when this event happens. The server still operates in non-SSL mode. Check file permissions and available disk space in the file system from where the executable runs.

Description: The first SSL negotiation phase (handshake) between the client and server did not complete successfully.


Cause: There could be many reasons for this event condition; typical ones include:

• Client and server don't support compatible versions of SSL

• Both sites do not agree on the cipher specification (for instance, client wants a strong cipher suite but server only supports weaker ones)

• Server's certificate not issued by any certificate authority trusted by the client.

Effect: The event is of warning severity: SSL operation not initiated properly for the particular client/server session. This event has no effect on non-SSL operations, nor does it indicate that an SSL operation cannot start on other socket connections.

Action(s): Examine the error string and correct the error condition accordingly.



��$��"��(�*�

System Log Events

��"��'��

Description: An error occurred during the SSL handshake phase when the client uses TLS command to initiate a secure session.


Cause: Errors occurred during the SSL handshake after client issues the STARTTLS command. There could be many causes for this event. The most common ones are:

• Client and server support non-compatible versions of SSL

• Client and server don't agree on a cipher specification supported by both

• Server doesn't provide SSL functionality

• Server's certificate not recognized

Effect: The event is of critical severity for SSL operations, but the socket is still operational for non-SSL operations.

Action(s): Examine the error string description; act according to corresponding error conditions.

Description: A request for heap storage using operator new failed. Using program heuristics, it appears that the heap is corrupted.

Parameters: return: current value from sbrk(0).

soft: soft limit on process heap size in bytes.

hard: hard limit on process heap size in bytes.

soft: soft limit on process virtual memory size in bytes.

hard: hard limit on process virtual memory size in bytes.

Cause:

Effect: The event is of major to critical severity. The process will be unable to perform properly. Depending on which process is reporting this event, the effect could have serious impact on the system.

Action(s): • If the process is a server, restart it.

• Contact your InterMail vendor.

Log Events


��$��

��

Description: The MSS shared memory table is full. Cannot access additional message stores until some close.

Parameters: number: number of currently open mailboxes

Cause: • An extremely heavily loaded system.

• The size configured for the shared memory table is too small.

• Another system or InterMail error.

Effect: The event is of critical severity. New messages unnecessarily deferred and many customers unable to retrieve mail.

Action(s): • Use immssshare to examine the size and contents of the shared memory table.

• Check for other system and InterMail errors that would indicate heavy load on the system or configuration problems.

Description: A request for number bytes of heap storage using malloc() failed.

Parameters: number: number of bytes requested.

Cause: • Out of virtual memory, that is, too many large processes running on this machine.

• Corruption of the heap.

Effect: The event is of major severity. The process will be unable to perform properly.

Action(s): • Check the amount of virtual memory available on the machine.

• If the process is a server, restart it.



9��

Description: A request for heap storage using operator new failed.

Parameters: return: current value from sbrk(0).

soft: soft limit on process heap size in bytes.

hard: hard limit on process heap size in bytes.

soft: soft limit on process virtual memory size in bytes.

hard: hard limit on process virtual memory size in bytes.

Cause: Using program heuristics, it appears that the heap is exhausted.

Effect: The event is of major to critical severity. The process is unable to perform properly. Depending on which process is reporting this event, the effect could have serious impact on the system.

Action(s): • Check the amount of virtual memory available on the machine.

• If the process is a server, restart it.


AConfiguration Keys by Server

Each configuration key influences the behavior of one or more InterMail servers. The sections that follow group individual keys according to the servers they control.

For details on any key, please refer to Chapter 2 of this manual.

Common Configuration KeysThe keys listed below affect the behavior of all InterMail servers.

• <server>_opt

• <server>_run

• abortIfLogFails

• adminPort

• binDir

• bodyDataBuffer

• cacheLimitInKB

• clientHeaps

• commonGroup

• commonUser

• configRecorderSize

• confServHost

• confTimeStamp

• defaultStackSizeInKB

• dirRmeHosts

• domainName



• eventMaxWait

• fatalSigHandlers

• fileDescriptors

• gmtLogTimes

• installDir

• InterMailVersion

• licenseKey

• licenseWarnThresholdDays

• listenBacklog

• logDir

• loginNameConvertFrom

• loginNameConvertTo

• logNamedPipeMode

• logRecorderSize

• logToSystem

• maxThreads

• messageTracing

• minFreeDiskSpaceInKB

• mutexSerialNumbering

• netTimeout

• nlsDir

• pidDir

• reportParamsInterval

• rmeAccessList

• rmeConnectTimeout

• rolloverAtLogSizeKB

• rolloversPerDay

• rolloverTimeZero

• RTMIabortOnSharedMemoryFail

• RTMIDisable

• runDir

• servWarnToStderr

Configuration Keys by Server


• sharedDir

• statNamedPipeMode

• statRecorderSize

• tmpDir

• traceNamedPipeMode

• traceOutputLevel

• traceRecorderSize

• traceToStderr

• updateServerDN

• useBoundThreads

• useMmapReads

• useMmapWrites

MTA Configuration KeysThe keys listed below control the behavior of the Message Transport Agent (MTA).

• advertiseProduct

• allowEtrn

• allowExpn

• allowHelp

• allowQsnd

• allowTLS

• allowVrfy

• alwaysQueue

• alwaysTryFirst

• alwaysTryFirstList

• autoReplyCharset

• autoReplySuppressList

• blockAddresses

• blockConnections

• blockDomains

• blockLocalNoAcct

• blockPerAccount



• blockReplyCode

• blockReplyText

• blockTheseAddresses

• blockTheseDomains

• blockTheseIPs

• blockTheseUsers

• blockUsers

• bounceFailureBody

• bounceFailureHeader

• bounceOnQuotaFull

• bounceSuccessBody

• bounceSuccessHeader

• bucketCount

• canonicalize

• checkAuthentication

• clientConnectionLimitTable

• clientLineLengthLimit

• completionMethod

• convertDomainLiterals

• createsMboxes

• defaultDomain

• deferOnMxLookupFail

• deferProcessInterval

• dirRmeConnections

• dirRmeMaxSecondaryCalls

• domainUpdateInterval

• dropConnections

• dropMaxMessageRCPTs

• dropRCPTsReplyText

• dropTheseIPs

• Error-Actions/acctInactive

• Error-Actions/acctInvalidUser



• Error-Actions/badReturn

• Error-Actions/filtActionBounce

• Error-Actions/msLimitMsgSize

• Error-Actions/msLimitNumMsgs

• Error-Actions/msLimitTotalSize

• Error-Actions/msNoAllowDeliver

• Error-Actions/mtaHostInvalid

• Error-Actions/mtaMaxMtaHopCountExceeded

• Error-Actions/mtaMessageDelivered

• Error-Actions/mtaMessageExpanded

• Error-Actions/mtaMessageQueuedTooLong

• Error-Actions/mtaMessageRejected

• Error-Actions/mtaMessageRelayed

• Error-Actions/mtaMessageTooLarge

• Error-Actions/mtaMsgNoRecipients

• Error-Actions/mtaRecipientsRejected

• Error-Actions/mtaSenderRejected

• Error-Actions/smtpClientMailLoopDetected

• Error-Actions/smtpDnsBadConfig

• Error-Actions/smtpProtocolNotSupported

• Error-Code/<keyName>

• Error-Text/<keyName>

• hostnameAliasList

• incomingMailFilter

• inDeliveryDeferKb

• inDeliveryRejectKb

• inDeliveryStopDeferProcessKb

• logMailBoxCreation

• mailRoutingHost

• mailRoutingTable

• maxAutoReplyMsgLenKb

• maxBadCommands



• maxDirectDelivery

• maxDirectKB

• maximumMtaHops

• maxMessageSizeInKB

• maxMssDeliverCount

• maxNullSenderRCPTs

• maxQueueTimeInHours

• mimeParseMode

• minQueueIdleTime

• msgDelivererNumThreads

• msgValidatorNumThreads

• mssDeliverTimeoutSecs

• mtaSpool

• noLocalDelivery

• outboundDeferProcessInitialWait

• outboundDeferProcessInterval

• queueSplitFactor

• rcptHarvesterCount

• rcptHarvesterTTLMinutes

• rcptMaxHarvesters

• rcptPotentialHarvesterTTLMinutes

• rejectInvalidFromAddr

• rejectDnsServer

• rejectSenderBadAddress

• rejectSenderBadDomain

• rejectSenderIpDomain

• rejectSenderNoDomain

• relayDestAllowList

• relayDestDenyList

• relayHost

• relayLocalDomainsOk

• relayLocalMustExist



• relayMaxRCPTs

• relayNullRestricted

• relayReplyCode

• relayReplyText

• relaySourceDomainList

• relaySourceLocalIpList

• relaySourcePolicy

• relaySourceRemoteIpList

• requireCrLf

• requireSecureAuth

• rewriteDomains

• rewriteGatewayHeaderList

• rewriteHeaderList

• rewriteMaxMtaHops

• rewriteOnlyLocal

• rewritePrimary

• rewriteSaveOrig

• scanOldMessagesIntervalInHours

• serverLineLengthLimit

• serverTotalLinesLimit

• sidelineMessages

• sidelineNullToMany

• sidelineNumRcpts

• sidelineNumRCPTsPerConnection

• smtpAcceptNumThreads

• smtpDeliverNumThreads

• smtpPort

• smtpQueueBucketCount

• smtpQueueProcessNumThreads

• sslCacheAgeSeconds

• sslCacheBucketLen

• sslCacheBucketNum



• sslCertChainPathAndFile

• sslCertPassword

• sslSmtpPort

• sslTrustedCertPathAndFile

• sslUseSessionCache

• subDomains

• timeoutClientData

• timeoutClientDataDot

• timeoutClientDataSend

• timeoutClientGreet

• timeoutClientHelo

• timeoutClientMailFrom

• timeoutClientQuit

• timeoutClientRcptTo

• timeoutClientRset

• timeoutServerCommand

• timeoutServerData

• timeoutServerDelivery

• timeoutServerDeliveryRejection

• useContentDisposition

• useMx

• validatorBatchSize

• verifyDeferOk

• verifyRcpts

MSS Configuration KeysThe keys listed below control the behavior of the Message Store Server (MSS).

adminMessageStoreName

autoReplyDefaultMessage

autoReplyExpireDays

backupMode

bounceQuotaNotice



checkPointInterval

checkPointRetryInterval

cosMinUpdateSeconds

dbLogFileMaxSizeKb

dbMboxCacheSizeinKB

dbMboxPageSizeinKB

dbMsgIdCacheSizeinKB

dbMsgIdPageSizeinKB

dbVerboseFlag

defaultAdminName

dupMessageDetect

idleFlushTimeoutSecs

imboxcopyNumThreads

imboxmigrateNumThreads

maxBounceNotices

maxFolders

maxKeywordLength

messageFilesDir

messageReadTracing

msgFileCacheSizeInKB

mssBasePort

nearQuotaNotice

numMboxDbFiles

numMsgIdDbFiles

popLockIdleTimeout

serverThreadStackSizeInKB

welcomeMsgId



Directory Server Configuration KeysThe keys listed below control the behavior of the Directory server.

• backupMode

• checkPointInterval

• checkPointRetryInterval

• clientTimeout

• configFiles

• dbSuffix

• dirRmePort

• loginFilter

• ldapAccessList

• ldapClientTimeout

• ldapConfigFiles

• ldapDbEntryCacheSizeInKB

• ldapDbEntryPageSizeInKB

• ldapDbIndexCacheSizeInKB

• ldapDbIndexPageSizeInKB

• ldapDbPageSizeInKB

• ldapEntryCacheMaxCount

• ldapEntryCacheMaxSizeKb

• ldapHost

• ldapIndices

• ldapNumEntryDbFiles

• ldapNumIndexDbFiles

• ldapOperationLimit

• ldapRepLogFile

• ldapRepLogRollHours

• ldapRootDn

• ldapRootPwd

• ldapSchemaCheck

• ldapSizeLimit

• ldadTimeLimit



• numUserDBFiles

POP Server Configuration KeysThe keys listed below control the behavior of the POP server.

• allowedIPs

• badPasswordDelay

• badPasswordWindow

• clientTimeout

• createsMboxes



• initClientTimeout

• lockTimeout

• loginDefaultDomain

• loginDefaultDomainTable


• maxBadPassword

• maxBadPasswordAddrs

• maxBadPasswordDelay

• maxBadPasswordUsers

• maxPasswordFailures

• maxSessions

• moveRetrieveErrors

• pop3Port

• popProxyHost

• popProxyPort




• sslCertChainPathAndFile

• sslCertPassword

• sslPop3Port



• sslTrustedCertPathAndFile


IMAP Server Configuration KeysThe keys listed below control the behavior of the IMAP server.

• badPasswordDelay

• badPasswordWindow

• clientTimeout

• createsMboxes


• dirServName


• imap4Port

• loginDefaultDomain

• loginDefaultDomainTable


• maxBadPassword

• maxBadPasswordAddrs

• maxBadPasswordDelay

• maxBadPasswordUsers

• maxKeywordLength

• maxMsgTextCache

• maxPasswordFailures

• maxSessions




• sslCertPassword

• sslImap4Port




Configuration Server Configuration KeysThe keys listed below control the behavior of the Configuration server.

• confServPort

• extraCopyConfigDbPath

• serverTimeout

• versionConfigDB

Manager Server Configuration KeysThe keys listed below control the behavior of the Manager server.

• legalHosts

• mgrServPort

SNMP Server Configuration KeysThe keys listed below control the behavior of the SNMP server.

• masterAgentHosts

• snmpReconnectNapTime

• trapMask

• trapQueueSize




BSupported RFCs

This chapter lists the open Internet mail standards that InterMail complies with. These standards, called Requests for Comment (RFCs), are codified by the Internet Engineering Task Force (IETF).

To learn more about Internet mail standards, see the Internet Mail Consortium’s Internet Mail Standards Web page:

http://www.imc.org/

To learn more about the IETF, visit their Web page:

http://www.ietf.org/

The RFCs are:

RFC Title

821 Simple Mail Transfer Protocol

822 Standard for the Format of ARPA Internet Text Messages

974 Mail Routing and the Domain System

1047 Duplicate Messages and the SMTP

1122 Requirements for Internet hosts - Communication Layers

1123 Requirements for Internet Hosts -- Application and Support

1157 Simple Network Management Protocol (SNMP)

1212 Concise MIB Definitions

1566 Mail Monitoring MIB

1777 Lightweight Directory Access Protocol

1778 The String Representation of Standard Attribute Syntaxes

1779 A String Representation of Distinguished Names



1798 Connection-less Lightweight X.500 Directory Access Protocol

1823 The LDAP Application Program Interface

1846 SMTP 521 Reply Code

1854 SMTP Service Extension for Command Pipelining

1869 SMTP Service Extensions

1870 SMTP Service Extension for Message Size Declaration

1891 SMTP Service Extension for Delivery Status Notifications

1892 The Multipart/Report Content Type for the Reporting of Mail System Administrative Messages

1893 Enhanced Mail System Status Codes

1894 An Extensible Message Format for Delivery Status Notifications

1939 Post Office Protocol - Version 3

1960 A String Representation of LDAP Search Filters

1985 SMTP Service Extension for Remote Message Queue Starting

2045 MIME 1: Format of Internet Message Bodies

2046 MIME 2: Media Types

2047 MIME 3:Message Header Extensions for Non-ASCII Text

2060 INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4 Rev.1

2249 Mail Monitoring MIB

2359 IMAP4 UIDPLUS Extension

2421 Voice Profile for Internet Mail - Version 2

2487 SMTP Service Extension for Secure SMTP over TLS

RFC Title


CLicense Information

This appendix contains license information related to InterMail Kx.

InterMail Licensing AgreementTHIS SOFTWARE IS PROVIDED “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE.COM BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEM-PLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCURE-MENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Apache Server LicenseRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment:

“This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/).”

4. The names “Apache Server” and “Apache Group” must not be used to endorse or promote products derived from this software without prior written permission.

5. Redistributions of any form whatsoever must retain the following acknowledgment:“This product includes software developed by the Apache Group for use in the Apache HTTP server project (http://www.apache.org/).”

THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAM-



AGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL-ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This software consists of voluntary contributions made by many individuals on behalf of the Apache Group and was originally based on public domain software written at the National Center for Supercom-puting Applications, University of Illinois, Urbana-Champaign. For more information on the Apache Group and the Apache HTTP server project, please see http://www.apache.org.

EMANATEInterMail incorporates the EMANATE server as part of its monitoring functionality. Software.com licenses EMANATE pursuant to a license agreement with SNMP Research International, Incorporated. The copying and distribution of EMANATE is with the permission of SNMP Research International, Incorporated.

GNU General Public License Version 2, June 1991

Copyright (C) 1991 Free Software Foundation, Inc.

59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

[This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.]

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By con-trast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.

This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the soft-ware or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipi-ents all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library.

Also, for each distributor’s protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recip-ients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors’ reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone’s free use or not licensed at all.

License Information


Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don’t assume that anything in it is the same as in the ordinary license.

The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a util-ity program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such.

Because of this blurred distinction, using the ordinary General Public License for libraries did not effec-tively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better.

However, unrestricted linking of non-free programs would deprive the users of those programs of all ben-efit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a “work based on the library” and a “work that uses the library”. The former contains code derived from the library, while the latter only works together with the library.

Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one.

GNU LIBRARY GENERAL PUBLIC LICENSE

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Pub-lic License (also called “this License”). Each licensee is addressed as “you”.

A “library” means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

The “Library”, below, refers to any such software library or work which has been distributed under these terms. A “work based on the Library” means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term “modification”.)

“Source code” for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.

Activities other than copying, distribution and modification are not covered by this License; they are out-side its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.

1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.



You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) The modified work must itself be a software library.

b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.

c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.

d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.

(For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-sup-plied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose per-missions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.

Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU Gen-eral Public License applies to all subsequent copies and derivative works made from that copy.

This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

If distribution of object code is made by offering access to copy from a designated place, then offer-ing equivalent access to copy the source code from the same place satisfies the requirement to dis-tribute the source code, even though third parties are not compelled to copy the source along with the object code.

5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a “work that uses the Library”. Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

License Information


However, linking a “work that uses the Library” with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a “work that uses the library”. The executable is therefore covered by this License. Section 6 states terms for distribu-tion of such executables.

When a “work that uses the Library” uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.)

Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself.

6. As an exception to the Sections above, you may also compile or link a “work that uses the Library” with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the cus-tomer's own use and reverse engineering for debugging such modifications.

You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:

a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable “work that uses the Library”, as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable contain-ing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)

b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of perform-ing this distribution.

c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.

d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:

a) Accompany the combined library with a copy of the same work based on the Library, uncom-bined with any other library facilities. This must be distributed under the terms of the Sections above.



b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly pro-vided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distrib-ute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.

10. Each time you redistribute the Library (or any work based on the Library), the recipient automati-cally receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipi-ents’ exercise of the rights granted herein.

You are not responsible for enforcing compliance by third parties to this License.

11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the condi-tions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Founda-tion. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.

14. If you wish to incorporate parts of the Library into other free programs whose distribution condi-tions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we some-

License Information


times make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software gen-erally.

NO WARRANTY

BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTH-ERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PRO-VIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANT-ABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDIS-TRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUS-TAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

OracleOracle Programs are the proprietary products of Oracle and are protected by copyright and other intellec-tual property laws. Customer acquires only the right to use Oracle Programs and does not acquire any rights, express or implied, in Oracle Programs or media containing Oracle Programs other than those specified by License. Oracle, or its licensor, shall at all times retain all rights, title, interest, including intellectual property rights, in Oracle Programs and media.

The Regents of the University of California Copyright

InterMail includes software that is copyright © 1990, 1993, 1994, The Regents of the University of Cali-fornia. All rights reserved.

This code is derived from software contributed to Berkeley by Mike Olson.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Re-distributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Re-distributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribu-tion.

3. All advertising materials mentioning features or use of this software must display the following acknowledgment: This product includes software developed by the University of California, Berke-ley and its contributors.

4. Neither the name of the University nor the names of its contributors may be used to endorse or pro-mote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL



DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOW-EVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The Regular Expression Routines1. Permission is granted to anyone to use this software for any purpose on any computer system, and to

alter it and redistribute it, subject to the following restrictions:

2. The author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from flaws in it.

3. The origin of this software must not be misrepresented, either by explicit claim or by omission. Since few users ever read sources, credits must appear in the documentation.

4. Altered versions must be plainly marked as such, and must not be misrepresented as being the orig-inal software. Since few users ever read sources, credits must appear in the documentation.

5. This notice may not be removed or altered.

RSA Data Security, Inc. MD5 Message-Digest Algorithm

License to copy and use this software is granted provided that it is identified as the “RSA Data Security, Inc. MD5 Message-Digest Algorithm” in all material mentioning or referencing this software or this function.

License is also granted to make and use derivative works provided that such works are identified as “derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm” in all material mentioning or referencing the derived work.

RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided “as is” without express or implied warranty of any kind.

These notices must be retained in any copies of any part of this documentation and/or software.


Glossary

absolute pathnameThe path to a file beginning at the root directory. See also relative pathname.

accountA directory entry containing attributes for a user. An account is used by InterMail and other applications, and includes one or more e-mail addresses, instructions for mail delivery, and auto-reply information. An account typically corresponds to an individual computer user, and is typically associated with a mailbox that stores the messages that the account receives. An account is synonymous with an LDAP Person entry in the ISD.

account class-of-service attribute valueA value for a class-of-service attribute that is relevant only to a specific account. The Directory cache uses it when returning a resolved class-of-service attribute value to a client in the evaluation of a class-of-service rule. In some situations, the account class-of-service attribute acts as a “user preference.” When present, an account class-of-service attribute value takes precedence, or overrides, the corresponding class-of-service attribute value.

See also class-of-service attribute value.

account statusAn account attribute that defines the current state of the account. The status of an account determines whether normal delivery of mail should occur for the account. The available account status types are Active (normal delivery), Maintenance (message delivery is temporarily delayed), Suspended (message delivery is denied), Deleted (message delivery is permanently disabled), and Proxy (delivery occurs to another mail system).

address completionThe automatic correction of an e-mail address that is not SMTP-compliant. As required by the SMTP protocol, recipient addresses must include both a username and a domain. If a username is present, but not a domain, InterMail appends a default domain name to the username to form a complete address. For example, if the address completion domain is software.com, and mail arrives for john.doe, the InterMail system completes the address by appending the default domain name and creates the recipient address [email protected].

Address completion is carried out only when a message would be otherwise undeliverable because of an address error.



administration utilityA command-line tool used to search for and modify data and to observe and change behavior in an InterMail system. There are commands for directory, account, mailbox, server, and log management, as well as for monitoring system diagnostics.

administrative mailboxA mailbox that stores default account information for a new user’s mailbox, including new account information, default mailbox data, and customer support. An administrative mailbox differs from other mailboxes in that it is strictly for administering account information, not for message retrieval.

alias1. An alternative name that is usually short and easy to remember.

2. On Web servers, a way to map an incoming request for a Web page. When an alias appears in a URL, the original address replaces the alias.

API (application programming interface)A set of routines that defines how programmers may access a particular InterMail service, such as the ISD, a mailbox, or a log file. APIs are typically used to enable utilities to access InterMail services, and to enable provisioning and other applications to be integrated with InterMail.

attachmentPortions of a message that are separate from the main body of the mail message and are not automatically displayed in a mail client, instead requiring some further action from the user.

attributeInformation describing one trait of a directory object. Each attribute has a name followed by one or more values. For example, the attribute o, belonging to the object class organization, could have the value Software.com. The attribute ou, belonging to the object class organizationalUnit, could have the value engineering.

attribute constraintAn attribute of an entry that governs how the other attributes of that entry may be modified. Attribute constraints define which administrators and users (if any) may create and modify attributes, and which legal values they may assign to the attributes.

attribute valueThe data associated with an attribute. For example, 555-1212 is an attribute value for the attribute telephoneNumber. Attributes may be single-valued or multiple-valued.

authenticationThe ability of one entity to determine the identity of another entity. Typically, this involves the use of a username and password pair or of a proprietary key.

Glossary


auto-reply featureA feature associated with InterMail accounts. When mail arrives for an account that uses the auto-reply feature, InterMail automatically sends the account’s auto-reply message to the sender of the original message.

availabilitySee high availability.

blockingSee mail blocking.

Body fileA temporary file that contains the text of a message and any attachments. It is created, along with the associated Control and Header files, when mail is secured on disk.

bounce messageA message that the MSS transmits to the sender of a message that has bounced. Also called bounce notice.

bouncingThe process of returning an undeliverable message to its sender.

bucketA subdirectory for storage of message files or message components (such as a message body, or message Control files). On the MSS and Queue servers, the use of buckets for load balancing enhances system performance.

canonicalizationA method of completing Mail-From addresses on incoming messages. When the InterMail canonicalize feature is active, the default domain name (defined in the defaultDomain configuration key) is used to complete Mail-From addresses that lack a domain. Addresses completed in this way are said to have been canonicalized.

certificateA key used as part of an authentication strategy for users. InterMail uses certificates during MTA and all transactions involving SSL.

child processA process created by another process. The creating process is the parent process.

class of serviceA set of permissions, resource limits, and default user preferences shared by a set of accounts that determines, among other things, the services that the users of each associated account may access. Each permission, resource limit, and preference is represented by a specific class-of-service attribute.



class-of-service attributeAn attribute of a class-of-service entry in the directory. Each class-of-service attribute defines a permission, resource limit, or preference that affects the set of accounts associated with the class of service.

class-of-service attribute ruleA value that defines the relationship between a class-of-service attribute and the account class-of-service attribute values (for example, whether the account class-of-service attribute value takes precedence over the class-of-service attribute value).

class-of-service attribute valueThe value assigned to a class-of-service attribute that applies to all accounts associated with the class of service. Sometimes this is referred to as a global COS attribute value to differentiate it from the account COS attribute value.

See also account COS attribute value.

Configuration databaseThe text file that contains all configuration keys and their associated values.

configuration keyA parameter defined in the master Configuration database and replicated on each host’s local Configuration database (config.db file) that represents the local and global configuration settings for all InterMail servers. Configuration keys are represented in the form “path/name:value”, where “path” defines the scope of the key, “name” identifies the key, and “value” specifies the value of the key.

Configuration serverThe InterMail server that holds the master Configuration database and distributes the latest version of it to all InterMail hosts. The Configuration server runs on a single host.

consumer serverThe destination server for replicated data. In InterMail, the consumer server is the Directory Cache server.

Control fileA temporary file that contains information about a message, including its current status in the delivery process and the names of the corresponding Header and Body files.

cookieA piece of information that a Web server provides to a Web client for identification. This information contains data that the server can retrieve later. In addition to tracking details as you browse on the Internet, cookies also help the server remember when you previously visited a site.

Glossary


deferred mailMail that the MTA cannot deliver immediately, either because a remote mail host is down or because the MSS or Directory Cache server is temporarily unavailable. Deferred mail goes to the Queue server for later delivery.

Directory Cache serverA component of the ISD that contains a copy of all or part of the master Directory database in its local cache database. The Directory Cache server is capable of servicing the same read and write requests as the Directory server and is regularly updated from the Directory server, preventing bottlenecks to the master Directory database and ensuring quick response time to queries by other servers.

Directory databaseA single Oracle relational database that is the authoritative master version of InterMail account information, including an end user’s domain, username, password, class of service, e-mail address, and delivery information. Directory cache servers communicate with the Directory server, which in turn accesses the Directory database, to get the updates to their local cache databases. The Directory database is a component of the ISD, together with the Directory server, Directory Cache servers, and Directory Cache databases.

Directory Information Tree (DIT)An LDAP term for the hierarchical structure that contains all directory entries. A DIT takes the form of an inverted tree, with the root at the top and the branches and leaves below it. Each entry in the DIT has a distinguished name (DN) that uniquely identifies it within the tree, and a relative distinguished name (RDN) that uniquely identifies it among its peers at any node in the tree.

Directory serverThe component of the ISD that maintains an authoritative master copy of the Directory database. It contains Oracle client libraries to communicate with the Directory database and is responsible for storing replication information that is read by the Directory Cache servers.

disk arrayA group of multiple physical drives tied together into logical units (LUNs) to support disk striping and/or mirroring. Also called RAID (Redundant Array of Inexpensive Disks).

disk stripingThe writing of data blocks across multiple disks in order to enhance throughput.

distinguished name (DN)An LDAP term for the name of a directory entry that uniquely identifies the entry by providing a complete pathname through the Directory Information Tree (DIT), analagous to a filename composed of a path of directory names in an operating system.



distributed architectureA system design that allows a single software application to span several independent pieces of hardware. Some benefits to a distributed architecture system are incremental/modular backup, possible failure only of single points (as opposed to failure of the entire system), security, and scalability.

domainOne or more IP addresses corresponding to a particular organization. For example, software.com is a domain that contains addresses in the 10.2.6.x Class C IP network.

domain name system (DNS)A system in which names are assigned to IP (Internet protocol) addresses. This structured system contains a hierarchy based on a proper name and type of organization, such as .org, .com, .edu, or .mil. DNS has two primary benefits. First, it provides users with a convenient and easy path to find an organization (with human-readable names instead of nonintuitive numbers). Second, it supports name lookup with a system of name servers that are dedicated to maintaining DNS records, polling for DNS records, and recording new entries.

draining (of a server)The process of shutting down a server without interrupting any current client connections. When a server is drained, it does not accept any new connections and waits for all of its current connections to close before shutting down.

See also stopping, killing.

DSN (delivery status notification)Return notification sent to e-mail senders on other systems that also support DSN informing them of e-mail delivery success, failure, or delay.

e-mail addressThe combination of a username, followed by an @ symbol, followed by a domain name. For example, [email protected] is an e-mail address, where joe.schmoe is the username and software.com is the domain name.

empty addressAn envelope or header address field that contains no information.

entryThe basic unit of information stored in a directory. Entries consistsof a collection of attributes.

envelopeThe portion of an InterMail message that contains the RCPT TO and MAIL FROM addresses, allowing the message to be delivered to its proper recipients. Unlike headers, the envelope is not a visible part of the message.

See also header.

Glossary


environment variableA variable that defines how the user’s environment responds to commands. A user or a program may set an environment variable. Common examples of environment variables include PATH statements and library paths.

ESMTP (Extended Simple Mail Transfer Protocol)The protocol used by the server that processes mail queue requests when the ETRN command is executed.

ETRN (extended turn)A mail-queue-processing option used in conjunction with SMTP. ETRN instructs remote mail hosts to attempt delivery of queued messages. This is useful if your server has a PPP or SL/IP connection or a similar intermittent connection to the Internet. ETRN is intended for use by connecting mail servers, but you can also execute the command manually to request queue processing.

failover strategyA strategy in which, in the event of machine failure, an alternate machine assumes the network identity of the failed machine and accesses its disk array through a second port. MSS hosts should use a failover strategy, because they host message data information that must be accessible at all times.

filter1. A program that accepts a certain type of data as input, transforms it, and then

outputs the transformed data. For example, a program that sorts names is a filter because it accepts the names in unsorted order, sorts them, and then outputs the sorted names.

2. A pattern through which data is passed. Only data that matches the pattern can pass through the filter.

folderA container for messages within a mailbox. By default, all InterMail mailboxes contain three folders: INBOX, SentMail, and Trash. Although POP mail users cannot see the folders, their messages automatically come from their INBOX folders.

Users with IMAP accounts can see folders within their mailboxes. They can create, delete, and move folders, as well as nest folders within other folders.

forwardingSee mail forwarding.

FTP (File Transfer Protocol)A set of systems and interfaces for transferring files across the Internet. Typically, FTP downloads files from a host machine or from an archive site to a user’s computer, or uploads files from a user’s computer to a host machine.



hashing1. The scrambling of a plain-text string (such as an account password) into an

apparently random string from which the original plain text cannot be recovered.

2. The provision of rapid access to data items in a database through distinguishing keys. A hash function acting on the item’s key produces a hash value that is an index to one of a number of “hash buckets” in a hash table.

headerAn address-related line inside a message, such as TO:, REPLY-TO:, and SENDER:. Headers are a visible part of the message but are not used to route mail.

Header fileA file that contains the header information for a message, including TO:, CC: , BCC: , FROM:, REPLY-TO:, and SENDER: information.

header rewritingThe process of changing the content of message headers (such as the TO:, CC: and FROM: headers) without changing the addressing in the message envelope. Header rewriting does not affect mail routing. It is primarily used to clean up the addresses that readers see in messages, and to hide proprietary address information when necessary.

high availabilityAvailability of a system to users 24 hours per day, seven days per week, without any significant interruption of service. Achievement of high availability requires the implementation of a variety of hardware and software strategies.

hostA machine in a network. For example, in venus.software.com, venus is the host.

HTTP (Hypertext Transfer Protocol)The protocol that both Web clients and Web servers use to communicate and transfer data across the Internet.

IMAP (Internet Mail Access Protocol)A protocol that allows users to view and manipulate messages directly on the MSS without having to download them. IMAP provides multiple, simultaneous access to mailboxes, and allows users to request only portions of messages, such as headers or attachments. IMAP users can also create new folders in their mailboxes and move or copy messages between folders.

IMAP serverThe InterMail server that handles requests for message retrieval from mail clients that support the IMAP protocol.

See also IMAP.

Glossary


inboxOne of the default folders for an InterMail mailbox. All new messages go into this folder as the MSS receives them.

incoming mailEvery message, whether addressed to a local user or destined for a remote recipient. After applying the rules for incoming mail, InterMail completes additional checks to determine whether the message’s final destination is local or remote.

See also outgoing mail.

indexIn database design, a list of keys (or keywords), each of which identifies a unique record. Indexes make it faster to find specific records and to sort records by the index field (that is, the field that identifies each record).

InterMail userA new UNIX user account created before installation on every host on which InterMail will be installed. InterMail files are in this user’s directory, and all InterMail processes run in this directory. To execute any administrative commands, or to administer InterMail in any way, the administrator must log in as the InterMail user.

InterMail user groupA UNIX user group created on every InterMail host. The InterMail user is the only member of this InterMail group.

IP addressThe network address on a TCP/IP network.

ISD (Integrated Services Directory)A set of services and databases used as a high-speed, scalable repository of account, administrative, and related information. The ISD consists of the Directory Cache servers, Directory server, Directory Cache databases, and Directory database.

ISP (Internet service provider)A company that provides connectivity to the Internet. Typically, an ISP provides user connections for the World Wide Web, FTP, news, and e-mail.

journaled file systemAny system that writes data to a journal. The journal is not lost in the event of a system crash and can therefore be used for recovery.

journalingThe process by which all Message File system transactions are saved in InterMail. A journal records every insertion, change, and deletion. Playing back the journal will re-create a full image of the Message File system. With a system of full backups, journaling provides a mechanism for full recovery of lost messages.



keySee configuration key, public key.

killing (of a server)The most forceful means of shutting down a server. Unlike stopping or draining, killing a server causes its client connections to be terminated immediately.

See also draining, stopping.

LDAP (Lightweight Directory Access Protocol)An Internet protocol that allows users to access and search a variety of otherwise incompatible directory systems across system, corporate, and international boundaries for information such as names, telephone numbers, and addresses.

LDIF (LDAP data interchange format)A standard way of representing directory data in a text file format, used to import and export data among LDAP directories. An LDIF entry consists of a series of lines of ASCII text, the first line specifying a distinguished name for the entry, and each subsequent line specifying an attribute of the entry.

leaf nodeA location in a DIT that is at the end of a branch. A leaf node has no descendents.

local deliveryDelivery of mail to a local mailbox.

local mailboxA mailbox created and maintained by the InterMail messaging system.

local mail domainA mail domain over which the InterMail system has complete authority. All users within a local mail domain have accounts in the ISD.

See also non-authoritative domain.

local userA user with an account in the ISD.

logical unit number (LUN)A single unit made up of one or more disks.

See also disk array, disk striping.

login nameThe name a user employs to start a POP or IMAP client session and begin the authentication process.

mail blockingA method of preventing specific users or systems from sending mail to your site.

Glossary


mailboxA storage area in the Message Store database for messages that are sent to an end user’s account. Typically, each account in the ISD is associated with a mailbox. Each mailbox has folders, which in turn contain the messages that have been received for the end user.

mailbox quotaA limit set on an account to control the size of the mailbox or the messages it contains. Quotas defined for each mailbox are the total size of messages in the mailbox, the maximum size of a single message in the mailbox, and the total number of messages in the mailbox.

mail forwardingThe sending of mail addressed to a particular destination to a different specified address. When a message arrives for an account for which mail forwarding is turned on, InterMail modifies the destination address to the one specified, and then sends the message to the modified location.

mail in deliveryAll messages that the system is actively engaged in delivering. Messages that have been explicitly deferred are not considered mail in delivery.

See also mail in process.

mail in processAll messages that have not yet been delivered or explicitly rejected. Mail in process includes all mail in delivery, plus all mail that has been explicitly deferred for later delivery, sidelined for review, or held due to an error condition.

mail loopA condition in which a message moves infinitely between two MTAs due to improper use of the empty address, or due to a lack of MTA hop specification.

mail routing tableA series of (typically) colon-delimited domains that can route mail if the specified destination domain for a message is unavailable.

Manager serverThe InterMail server that allows administrators to log on to a single InterMail host and start or stop any of the servers running on that host or on any other InterMail host. The Manager server runs on each InterMail host.

master agentAn SNMP agent that collects information from the subagents in the system for exchange with an SNMP network management system using the SNMP protocol. There is one SNMP master agent per system.



master Configuration databaseA database containing the authoritative list of InterMail system settings. The master Configuration database is used by the Configuration server to provide all InterMail servers with current configuration information.

master configuration hostThe host machine on which the master Configuration database and Configuration server are located.

message1. In an e-mail system, an individual piece of mail.

2. In computer systems in general, an information unit that the system sends back to the user or system operator with information about the status of an operation, an error, or other condition.

message agingA feature that permits deletion of old mail from the Message Store database, even if recipients have not read the mail. Message aging is useful for controlling the size of mailboxes and preventing over-quota conditions.

Message File systemThe file system located on the MSS that is responsible for storing the physical contents of a message, including the header (summary of the contents of the message) and the body (the text of the message and any attachments).

message relayingThe process of sending messages from one MTA to a second MTA for any of a number of reasons, including migration.

See also relay host.

Message Store databaseA database containing state information about messages stored in the Message File system.

MIB (Management Information Base)The database of information maintained by an SNMP agent that the network management system can query or set. InterMail supports querying only.

migrationThe process by which users’ mailboxes are moved from a “legacy” mail system (for example, Post.Office) to an InterMail system. The process of migrating mailboxes involves exporting account information from the old system, creating new accounts in InterMail, and then moving mailboxes to InterMail.

MIME (multi-purpose Internet mail extensions)A standard for multi-part, multimedia electronic mail messages and World Wide Web hypertext documents on the Internet. MIME provides the ability to transfer

Glossary


nontextual data, such as graphics, audio and fax. RFC 1341 defines the MIME standard.

mirroringThe writing of duplicate data to multiple devices (usually two hard disks) in order to protect against loss of data in the event of device failure. There are hardware implementations (sharing a disk controller and cables) and software implementations of this technique, which is a common feature of RAID (redundant array of independent disks) systems.

MSS (Message Store Server)The InterMail server responsible for hosting mailboxes and storing incoming messages.

MTA (Message Transport Agent) The InterMail server responsible for delivering messages. The MTA determines whether a message is destined for local or remote delivery, and then performs those tasks required to complete the delivery process.

multi-threadingThe ability of an individual server process to perform multiple tasks simultaneously. Multi-threading enhances system performance, resulting in higher message throughput.

mutexShort for mutual exclusion lock. Use of this type of lock excludes all threads other than the lock holder from any access to the locked resource.

MX record (mail exchanger record)An Internet MX record specifies a mail exchanger for a specific domain. The mail exchanger is the host machine whose task it is to deliver or forward mail for this particular domain. When the MTA attempts to deliver mail to a remote domain, it must first find the MX record for the machine that delivers mail for that domain.

non-authoritative domainA mail domain over which the InterMail system has partial authority. InterMail accepts messages for all users in a non-authoritative mail domain, but only some of those users have accounts in the ISD. Also called semi-local domain.

See also local mail domain.

object identifier (OID)A string of numbers separated by dots, used to uniquely identify objects in the directory. Each part of an OID represents a node in a hierarchical OID tree. This allows blocks of namespace to be delegated to individual organizations for their own use. For example, the InterMail object class policy is the string of numbers assigned to Software.com by the Internet Engineering Task Force (IETF), 1.3.6.1.4.1.2415, followed by a string of numbers designated by Software.com, 1.2.2.1. This creates an OID of 1.3.6.1.4.1.2415.1.2.2.1 for the object class policy.



object classA collection of required and optional attributes in a directory that defines a type of data. For example, person, organization, and domain are standard object classes in an LDAP directory.

orphan1. A child process left when a UNIX parent process creates it and then terminates.

2. A message file that exists in the Message File system without a corresponding referential pointer in the MSS.

See also widow.

outgoing mailMail whose final destination is a remote mail server.

See also incoming mail.

parent processA process that creates another process. The created process is a child process.

partitioningThe replication of Directory data to two or more Directory Cache servers. The servers typically have mutually exclusive sets of entries, which together constitute all of the data required for the application served by the Directory caches. Dividing accounts by region (for example, east and west) is an example of partitioning.

passwordThe string that a user enters when starting a POP or IMAP client session, after entering a login name.

pathThe specification of a file or directory in a hierarchical file system. The path usually lists the directories top-down, separating the directories by the pathname separator ("/" in UNIX, "\" in DOS).

permissionAn access privilege (for example, read and write) associated with a file or directory. Depending on the operating system, each file may have different permissions for different kinds of access and different users or groups of users.

pingA program that "bounces" a request off another computer over a network to see if the remote computer responds. If the ping comes back, the remote computer is alive.

Since ping works at the IP level, its server side is often implemented entirely within the operating system kernel and is thus probably the lowest-level test of whether a remote host is alive. A ping often produces a response even when higher-level TCP-based services cannot.

Glossary


POP (Post Office Protocol)The protocol used by most e-mail clients to retrieve e-mail from a mail server. There are two versions of POP. The first, POP2, became a standard in the mid-1980s and requires SMTP to send messages. The newer version, POP3, does not require SMTP.

POP serverThe InterMail server that handles requests for message retrieval from any client that supports the POP3 protocol. It communicates with the Directory Cache server to validate the user’s login name and password, and to obtain the name of the MSS host on which the user’s mailbox resides. The POP server also communicates with the MSS to service requests for message retrieval from the client.

portIn a communications network, an endpoint to a logical connection, with a unique port number. For example, port 110 is typically used for POP traffic.

See also reserved port, well-known port.

primary SMTP addressThe main address for a user’s account. Options such as forwarding and SMTP aliases use the information in this primary address as a source of forwarding information.

private keyA key used in public-key cryptography to perform a type of decryption. Private and public keys come in corresponding pairs.

A private key belongs to a single user only. Unlike a public key, which can be available to anyone, a private key remains secret to everyone except its user. It is used to decrypt data that has been encrypted with that same user’s public key.

See also public key.

processA single stream of instructions that may in turn spawn other processes.

proxyA server that acts as a surrogate for another server. The proxy receives messages, then relays them to another server where the end user’s account may actually reside. Proxying is used primarily during the migration process (when user accounts are moved from a legacy system to InterMail).

public keyA key used in public-key cryptography to perform a type of encryption. Public and private keys come in corresponding pairs.

User A may send a secure message to User B by obtaining User B’s public key. User A then encrypts all or part of the message with User B’s public key. After receiving the encrypted message, User B decrypts it with a corresponding private key.



A user’s public key can be made available to anyone who wishes to initiate an encrypted transaction with that user.

See also private key.

queue directoryThe root directory for the Queue server. The queue directory contains a series of subdirectories that store messages that the MTA cannot deliver immediately.

Queue serverThe InterMail server that is responsible for temporary storage of messages that the MTA cannot process immediately.

quotaSee mailbox quota.

quota thresholdA percentage of a quota value at which a user is warned about an impending quota violation.

redundancy (server)A condition in which multiple servers of a particular type exist to perform required tasks in an InterMail system. In such a system, the loss of any one server has a minimal effect on system operations.

relative distinguished name (RDN)An LDAP term for the most specific component of a distinguished name. A relative distinguished name must be unique among entries of the same parent in the Directory Information Tree (DIT).

relative pathnameThe path to a file relative to a given starting point. The starting point is typically the InterMail operational directory, which you can identify by typing:

echo $INTERMAIL

See also absolute pathname.

relay hostA backup host that functions as the MTA. A relay host can be a proxy host used in the migration process or an MTA that takes over for the primary MTA in a system.

relayingSee message relaying.

remote deliveryDelivery of a message to another mail server (as opposed to a local mailbox).

remote mail serverA mail server outside the InterMail system.

Glossary


remote recipientA recipient who does not have an account in the ISD.

replica setA set of identical Directory Cache servers that are interchangeable for the purpose of satisfying client requests. If one of Directory Cache server is unavailable, a client tries to communicate with the others, one at a time. Replica sets thereby function as a failover mechanism.

replicationThe process by which directory entries are automatically copied from the Directory server to one or more Directory Cache servers for local storage to provide greater performance, scalability, and reliability.

replication agreementA filter that specifies which directory entries and which of their attributes are copied and maintained by one Directory Cache server or by a replica set formed by several Directory Cache servers.

replication areaA set of objects and attributes to be replicated to a consumer server.

reserved portA port that, although not explicitly defined to carry a particular protocol or service, is within the range of well-known port numbers (0–1023). A reserved port is reserved for future use, and users should take care not to assign port numbers arbitrarily to reserved ports.

See also port, well-known port.

resource fileA file that defines a set of environment variables and user preferences to determine behavior during a session. Examples of resource files are .cshrc and .profile.

rewrite domainA domain name that serves as an alias for a local or non-authoritative domain.

RFC (request for comments)A series of notes about Internet standards and protocols. An RFC number designates each RFC. Once published, an RFC never changes. Any changes that are necessary become a new RFC with a new RFC number. Anyone may submit an RFC, but an RFC gains acceptance as an Internet standard only if it generates enough interest.

RME (remote method execution)The protocol that InterMail servers use to communicate the results of transactions between themselves.



rolloverIn an InterMail system, a means of conveniently archiving large log files to secondary storage without disrupting running applications. In log file rollover, the system closes the old log file, creates a new log file, and continues logging to the new file without interruption.

root directoryThe top-level directory on a disk.

routing hostA host machine that performs the functions of a router.

scalabilityThe ability to change the size or capacity of a system in proportion to the increase in resources used; for example, the ability to handle a larger number of users based on a proportionately greater hardware base.

schemaA description of the Directory database that sets the rules for what can be stored in the database, as well as how the Directory server and its clients handle information during search, modify, add, or delete operations. In LDAP-based directories, a schema is composed of object classes and attributes.

sideliningThe automatic placement of incoming mail suspected of being spam to a designated directory for special review and handling. Mail may qualify for sidelining if it originates from certain domains or addresses, if it is addressed to too many recipients, or if its origin is incomplete or missing. Sidelined mail that is found to be legitimate can be moved back into ordinary mail processing.

signatureInformation (such as name, telephone number, and address) automatically appended to outgoing e-mail messages.

SMTP (Simple Mail Transfer Protocol)An application-level TCP/IP protocol for e-mail on the Internet. SMTP defines the message format and message transfer agent. Although SMTP is text-based, MIME (Multipurpose Internet Mail Extension) and other encoding methods allow nontext attachments.

SMTP addressSee e-mail address.

SNMP (Simple Network Management Protocol)A widely used application-level protocol for network management. Network management applications can query management agents in network devices such as hubs, bridges, and routers. The hardware- or software-based management agents can report information about the device stored in the device’s MIB

Glossary


(Management Information Base). Although SNMP is a TCP/IP standard protocol, other non-TCP network types, such as Ethernet, also have SNMP implementations.

SNMP serverAn InterMail server that communicates with other InterMail servers (all except the Manager and Configuration servers) to gather useful system information and pass it to an SNMP monitoring station, which can be any remote host. Each InterMail system includes a single SNMP server. (You must supply your own monitoring system.)

spool directoryA directory on the MTA for messages that would normally go into the queue directory. The MTA normally operates in a stateless mode. However, if the system is configured to handle this operation and the Queue server becomes unavailable, the spool directory on the MTA stores all messages that are not immediately deliverable.

SSL (secure sockets layer)A transport-level security protocol for authentication and data encryption on the Internet. SSL negotiates security between clients and servers.

stateless modeA condition of independence. A stateless server request, for example, is an independent transaction, unrelated to any previous request. This simplifies the server design, because it does not require the server to allocate storage to deal with conversations in progress, or to free storage if a client fails in mid-transaction.

The MTA operates in a stateless mode. The Queue server handles all storage of mail in process.

statistics fileA file containing information about system performance.

stopping (of a server)The process of shutting down a server so that it stops immediately, regardless of the presence of client connections, but terminates client connections with meaningful error or status messages. This is the most common method of shutdown.

See also draining, killing.

sub-agentA component of a system that can exchange information with the system’s SNMP master agent. There can be one or more sub-agents per system.

supplier serverA server that supplies information to be replicated. In InterMail, the supplier server is the Directory server.



tablespaceA logical portion of an Oracle database for allocating storage for table and index data. Databases have one or more tablespaces, each made of one or more data files. Tables and indexes must exist within a tablespace. A tablespace can have many tables and indexes.

TCP/IP (Transmission Control Protocol/Internet Protocol)A networking protocol for communicating between heterogeneous networks and hardware and software platforms. Most of the Internet operates using TCP/IP. Practically all platforms offer TCP/IP support.

TCP, a transport-layer protocol, first establishes a connection between two systems. Then the sending system breaks transmitted data into bundles, called packets. Each packet carries a distinguishing sequence number that allows the receiving system to reassemble the packets into the original data. If the checksum of the result matches the original checksum, the receiving system acknowledges proper receipt of the packet. TCP attempts to retransmit lost or damaged packets.

IP is a network-layer protocol, and uses the 32-bit IP address, subnet mask, and default gateway to address and send packets to their proper destinations.

throttlingThe process of controlling the pace of mail flow by adjusting the threshold size of mail to be automatically deferred, the threshold size of mail to be automatically rejected, or the threshold size of mail to automatically cause work to stop on deferred mail (in order that current mail can be processed).

trace fileA file containing diagnostic information. Trace files track the flow of messages through the InterMail system and are useful for debugging and measuring system performance.

usernameThe portion of an e-mail address that precedes the @ symbol. For example, in the e-mail address [email protected], the username is joe.schmoe.

See also e-mail address.

welcome messageA message to greet new users and inform them of system policies, quotas, and so on. The welcome message is located in a special administrative mailbox, where the site’s message aging policy cannot delete it.

well-known portA port that is explicitly designated for a particular protocol or service. For example, port 110 is designated for the POP3 protocol. The well-known port numbers are in the range 0–1023.

See also port, reserved port.

Glossary


widowA message reference which appears in the Oracle tables on the MSS but for which there is no corresponding message file in the Message File system.

See also orphan.

wildcard accountAn administrative account with an address such as *@domain.com. This account is designed to receive all mail that does not exactly match some actual e-mail address.




Index

Symbols_opt, 9_run, 9

AabortIfLogFails, 10Account

C API class, 305Accounts

Creating, 216Deleting, 217Forwarding, 232, 234Getting, 218Listing, 222Local delivery, 233, 234Login name, 225Mailbox quotas, 227Modifying, 223Password, 222, 230Status, 228

AcctBadPswd, 436AcctBadPswdMax, 436AcctBadPswdMaxAddrs, 437AcctBadPswdMaxDelay, 437AcctBadPswdMaxFailures, 438AcctBadPswdMaxUsers, 438AcctDirCacheDown, 438AcctDirCacheError, 439AcctDirCacheUnknownError, 439AcctForwardInfoInvalid, 440AcctForwardInfoMissing, 440AcctForwardInfoQueryFail, 440AcctForwardTo, 441AcctImapNotAllowed, 441AcctInactive, 441AcctInvalidUser, 442AcctLookupFail, 442AcctMaintenance, 442AcctNontrustedLogin, 443AcctNotUser, 443AcctOtherFailure, 443

AcctPopFilterSyntaxInvalidRegex, 444AcctPopFilterSyntaxMissingSeparator, 444AcctPopFilterSyntaxMissingStart, 445AcctPopNotAllowed, 445AcctPswdBad, 445AcctSslImapNotAllowed, 446AcctSSlPopNotAllowed, 446AcctUnknownUser, 446Administration Commands, 259Administration commands

impopuserstats, 286administration commands

ldapadd, 253ldapdelete, 254ldapmodify, 255ldapmodrdn, 256ldapsearch, 257

adminMessageStoreName, 10adminPort, 11advertiseProduct, 11Alias addresses

Creating, 235Deleting, 236Listing, 237

allowedIPs, 12allowEtrn, 12allowExpn, 13allowHelp, 13allowQsnd, 14allowVrfy, 15alwaysQueue, 16alwaysTryFirst, 17alwaysTryFirstList, 19API libraries

InterMail C, 295InterMail Perl, 347, 427InterManager Perl, 393

Auto-reply, 228, 229autoReplyCharset, 20autoReplyDefaultMessage, 20autoReplyExpireDays, 21



autoReplySuppressList, 22

BbackupMode, 23badPasswordDelay, 23, 128badPasswordWindow, 24Batch loading

utility, 244batch loading

record sequence, 246record types, 245

binDir, 24blockAddresses, 25blockConnections, 26blockDomains, 27blockLocalNoAcct, 28blockPerAccount, 29blockReplyCode, 29blockReplyText, 30blockTheseAddresses, 30blockTheseDomains, 31blockTheseIPs, 32blockTheseUsers, 33blockUsers, 34bodyDataBuffer, 34bounceFailureBody, 35bounceFailureHeader, 36bounceOnQuotaFull, 37bounceQuotaNotice, 38bounceSuccessBody, 40bounceSuccessHeader, 41bucketCount, 41

CC API, 295cacheLimitInKB, 42CacheUpdateTimeTooLong, 483canonicalize, 42checkAuthentication, 43checkPointInterval, 153checkPointRetryInterva, 153Class of service

C API class, 325Class of Service Operations, 237Classes of service

Creating, 237Deleting, 239

clientConnectionLimitTable, 45clientHeaps, 46clientLineLengthLimit, 47clientTimeout, 48

commonGroup, 48commonUser, 49completionMethod, 49ConfBadChecksum, 447ConfBadKey, 448ConfChangeAssessment, 448ConfChangeInstall, 448ConfClientConnect, 449ConfCommonPort, 449ConfCommonPortRange, 450ConfDuplicateKey, 450ConfEndUpdate, 451ConfFixerFuncFailed, 451ConfFoundOtherMSS, 452configFiles, 50Configuration database, 2Configuration Keys, 5Configuration server, 2ConfInstallFailed, 452ConfInstallSucceeded, 453ConfInvalidHostName, 453ConfInvalidParmName, 454ConfInvalidProgName, 454ConfKeyAdded, 455ConfKeyDeleted, 455ConfLicenseExpired, 455ConfLicenseExpiringSoon, 456ConfLockFail, 456ConfMiscError, 457ConfMissingBracket1, 457ConfMissingBracket2, 457ConfMissingColon, 458ConfMissingRequiredParameter, 458ConfModNameSizeTooLarge, 459ConfMsgCatNotFind, 459ConfMsgCatStatFail, 460ConfNewerParmsReturned, 460ConfNoConnTrace, 461ConfNoDomainName, 461ConfNoHeader, 461ConfNonStandardPort, 462ConfNotAConfiguredHost, 463ConfNoUpdate, 462ConfOtherHostHasLocked, 463ConfParmChanged, 464ConfParmError, 464ConfParmsPush, 465ConfPortConflict, 465ConfPortConflictRange, 466ConfSdbPathNameAndFileRequired, 466ConfSearchDirsArraySize, 467

Index


ConfServerLock, 467ConfServerNotConfiguredForHost, 467ConfServerNotLocked, 468confServHost, 51confServPort, 51ConfStartUpdate, 468confTimeStamp, 52ConfWrongNumDynamicKeys, 468convertDomainLiterals, 53cosMinUpdateSeconds, 53CreateAccount, 216CreateAlias, 235CreateCos, 237CreateCosAttribute, 238CreateDomain, 211CreateRemoteForward, 231createsMboxes, 54

DData extraction utility, 242Data integrity checking, 251DbCacheConnect, 477DbCacheDisconnect, 477DbDatabaseError, 478DbInitNoPath, 479dbLogFileMaxSizeKb, 54dbMboxCacheSizeinKB, 55dbMboxPageSizeinKB, 55DbMessageFilesDirNotSpecified, 479dbMsgIdCacheSizeinKB, 56DbMsgIDMismatch, 480dbMsgIdPageSizeinKB, 56DbNameTooLong, 481DbNoMessageFileStorage, 481DbNumClientConnections, 482dbPageSizeInKB, 57dbSuffix, 57DbTooManyDirClientPool, 482DbValueTooLong, 482dbVerboseFlag, 57defaultAdminName, 58defaultDomain, 59defaultStackSizeInKB, 59deferOnMxLookupFail, 60

deferProcessInterval, 60DeleteAccount, 217DeleteAccountCos, 218DeleteAlias, 236DeleteCos, 239DeleteCosAttribute, 239DeleteDomain, 212DeleteRemoteForward, 231Directory checking operations, 252Directory database, 2directory management utilities

ldapadd, 253ldapdelete, 254ldapmodify, 255ldapmodrdn, 256ldapsearch, 257

dirRmeConnections, 61dirRmeHosts, 61dirRmeMaxSecondaryCalls, 62dirRmePort, 62DisableForwarding, 232DisablePOPDelivery, 233Domain

C API class, 301domainName, 63Domains

Creating, 211Default, 213Deleting, 212Listing, 213Modifying, 215Wildcard delivery, 214, 215

domainUpdateInterval, 63dropConnections, 64dropMaxMessageRCPTs, 64dropRCPTsReplyText, 65dropTheseIPs, 65dupMessageDetect, 66

EEnableForwarding, 234EnablePOPDelivery, 234entryCacheMaxCount, 66entryCacheMaxSizeKB, 67



Error-ActionsacctInactive, 67acctInvalidUser, 68badReturn, 69filtActionBounce, 70msLimitMsgSize, 71msLimitNumMsgs, 72msLimitTotalSize, 73msNoAllowDeliver, 74mtaHostInvalid, 75mtaMaxMtaHopCountExceeded, 76mtaMessageDelivered, 77mtaMessageExpanded, 78mtaMessageQueuedTooLong, 79mtaMessageRejected, 80mtaMessageRelayed, 81mtaMessageTooLarge, 82mtaMsgNoRecipients, 83mtaRecipientsRejected, 84mtaSenderRejected, 85smtpClientMailLoopDetected, 86smtpDnsBadConfig, 87smtpProtocolNotSupported, 88

Error-Code/, 88Error-Text/, 89Event logging

BdbAppInitFailed, 469BdbBadDataFormat, 469BdbCursorCreateFailed, 470BdbCursorOpFailed, 470BdbDatabaseNote, 471BdbDataInconsistency, 471BdbDeadlockDetected, 471BdbDeleteFailed, 472BdbFileOpenFailed, 472BdbGetFailed, 473BdbIndexRebuildFailed, 473BdbIndexRebuildSucceeded, 473BdbInitFailed, 474BdbMessageRecordMissing, 474BdbMsgIDMismatch, 474BdbPutFailed, 475BdbStartInBackupMode, 475BdbTxnAbortFailed, 476BdbTxnCommitFailed, 476KeywordTooLong, 507

eventMaxWait, 89extraCopyConfigDBPath, 90Extracting user data from InterMail, 242

FfatalSigHandlers, 91fileDescriptors, 92FiltActionBounce, 483

FiltActionBounceTwice, 484FiltActionConflict, 484FiltActionForward, 484FiltActionReject, 485FiltActionRejectTwice, 485FiltActionSideline, 486FiltActionSidelineTwice, 486FiltActionToss, 486FiltParseFail, 487FioBlockOnPipe, 487FioCloseFail, 488FioCopyFileFail, 488FioCreateFail, 489FioCreatePortFileFail, 489FioDirMissing, 490FioFcntlFail, 490FioFsyncFail, 491FioLinkFail, 492FioMakeDirFail, 493FioMknodFail, 493FioMmapFailed, 494FioMmapFileNotOpen, 494FioNoReaders, 494FioOpenDirFail, 495FioOpenFail, 495FioPipeHndlr, 496FioPipeOpenFail, 496FioPipeWrite, 497FioPipeWrtFail, 497FioPrematureEOF, 498FioReadFail, 498FioRenameFileFail, 499FioRmdirFail, 499FioSeekFail, 500FioStatFail, 500FioStatvfsFail, 501FioUnlinkFail, 501FioWriteFail, 502Folder

C API class, 317Forwarding addresses

Creating, 231Deleting, 231Listing, 235

GGetAccount, 218GetAccountCos, 220GetDefaultDomain, 213GetPassword, 222gmtLogTimes, 92

Index


HhostnameAliasList, 93

IidleFlushTimeoutSecs, 94IM_AcStatus, 305IM_CheckPassword, 311IM_Config, 329IM_CopyMsgs, 320IM_CreateAccount, 308IM_CreateCos, 327IM_CreateCosAttribute, 328IM_CreateDomain, 302IM_CreateFolder, 319IM_CreateForward, 313IM_CreateLogFile, 337IM_CreateMbox, 316IM_CreateMsg, 321IM_CreateReply, 324IM_DeleteAcCos, 312IM_DeleteAccount, 312IM_DeleteAlias, 313IM_DeleteCos, 327IM_DeleteCosAttribute, 329IM_DeleteDomain, 303IM_DeleteFolder, 319IM_DeleteFolderMsgs, 319IM_DeleteForward, 314IM_DeleteMbox, 316IM_DeleteMsg, 321IM_DeleteReply, 325IM_DisableAccountForwards, 314IM_Domain, 301IM_DomainType, 301IM_EnableAccountForwards, 314IM_Error, 299IM_Folder, 317IM_ForwardFlag, 305IM_FreeConfig, 330IM_FreeLogContext, 339IM_FreeLogMsg, 337IM_FreeMimeInfo, 333IM_InitApplication, 296IM_InitConfig, 330IM_InitLibrary, 297IM_InitLogContext, 339IM_InitLogMsg, 337IM_InitMimeInfo, 333IM_LocalDelivery, 305IM_Mbox, 315

IM_MimeInfo, 330IM_MoveMsgs, 320IM_Msg, 320IM_MsgFlagsIndex, 317IM_PwHashType, 305IM_ReadAccount, 312IM_ReadAccountAliases, 313IM_ReadAccountForwards, 314IM_ReadAccounts, 314IM_ReadAlias, 313IM_ReadConfig, 330IM_ReadCos, 327IM_ReadCosAttributes, 329IM_ReadCosNames, 327IM_ReadDomain, 302IM_ReadDomains, 304IM_ReadLogContext, 339IM_ReadLogMsgText, 337IM_ReadMbox, 315IM_ReadMsg, 321IM_ReadMsgBody, 322IM_ReadMsgHeader, 322IM_ReadMsgMimeInfo, 333IM_ReadPOP3, 313IM_ReadReply, 324IM_ReadSubDomains, 304IM_RenameFolder, 319IM_Reply, 323IM_ReplyType, 306IM_ResetAcCos, 311IM_ScanFolderMsgs, 320IM_SetCosAttribute, 328IM_SetMSSConnPoolSize, 316IM_Severity, 335IM_StringArray, 301IM_UnsetCosAttribute, 328IM_UpdateAcCos, 311IM_UpdateAccount, 310IM_UpdateAccountAddr, 312IM_UpdateCosAttribute, 328IM_UpdateDomain, 303IM_UpdateLogContext, 339IM_UpdateMsgFlags, 322IM_UpdateReply, 325IM_WriteLogMsg, 337imanLogin, 94imanOrg, 95imanPass, 95imanUID, 96IMAP Server, 1imap4Port, 96



ImapBadMsgNum, 502ImapCommandFailed, 503ImapCommandFailedReason, 503ImapConnBroken, 504ImapConnMade, 504ImapConnTimedOut, 504ImapDisconnected, 505ImapMaxSessions, 505ImapMSSError, 505ImapNoProxyLogin, 506ImapProtocolErr, 506ImapSyncError, 506ImapUIDOutOfOrder, 507imbadmsgfix, 260imbatchextract, 242imbatchload, 244imboxcopyNumThreads, 97imboxcreate, 261imboxdelete, 262imboxget, 262imboxmigrateNumThreads, 97imboxstats, 263imboxtest, 263imbucketscreate, 264imcmdlist, 265imconfedit, 266imconfget, 269imconfxlate, 270imctrl, 271

imdbcontrol, 207Account operations, 216Class of service operations, 237CreateAccount, 216CreateAlias, 235CreateCos, 237CreateCosAttribute, 238CreateDomain, 211CreateRemoteForward, 231DeleteAccount, 217DeleteAccountCos, 218DeleteAlias, 236DeleteCos, 239DeleteCosAttribute, 239DeleteDomain, 212DeleteRemoteForward, 231DisableForwarding, 232DisablePOPDelivery, 233Domain operations, 211EnableForwarding, 234EnablePOPDelivery, 234Execution options, 209GetAccount, 218GetAccountCos, 220GetDefaultDomain, 213GetPassword, 222ListAccountForwards, 235ListAccounts, 222ListAliases, 237ListCosAttributes, 239ListCosNames, 240ListDomains, 213Mail Delivery Operations, 231ModifyAccount, 223ModifyAccountPop, 225ModifyAccountSmtp, 225ModifyCosAttribute, 240SetAccountCos, 226SetAccountQuota, 227SetAccountStatus, 228SetAutoReply, 228SetAutoReplyHost, 229SetCosAttribute, 241SetPassword, 230SetProxyHosts, 230SetWildcardAccount, 214ShowCos, 241SMTP alias operations, 235Syntax, 208UnsetCosAttribute, 242UnsetWildcardAccount, 215UpdateDomain, 215

imdbmake, 272imdirmake, 272imfiltercheck, 98, 273

Index


iminboxlist, 274imintegcheck, 251imlogprint, 275imlogsum, 277immsgdelete, 278immsgdump, 279immsgfind, 280immsgmassmail, 281immsgprocess, 282immsgverify, 283immsinit, 284immsscall, 285immtacheck, 285imorphanrm, 286impopuserstats, 286impwdhash, 287imqueuesplit, 288imreplyctrl, 289imservctrl, 290imservdisplay, 291imservping, 292imservshutdown, 293imsmtpcheck, 293imspoollistoldfiles, 294imsysmon, 294incomingMailFilter, 98inDeliveryDeferKb, 99inDeliveryRejectKb, 100inDeliveryStopDeferProcessKb, 101indices, 102initClientTimeout, 102installDir, 103InterMail servers, 1interMailVersion, 103InterManager Perl API

MailCos, 420ISD (Integrated Services Directory)

adding new entries to, 253deleting entries from, 254modifying entries in, 255, 256searching, 257

LldapAccessList, 104ldapadd, 253ldapClientTimeout, 104ldapConfigFiles, 105ldapDbEntryCacheSizeInKB, 105ldapDbEntryPageSizeInKB, 106ldapDbIndexCacheSizeInKB, 106ldapDbIndexPageSizeInKB, 107

ldapdelete, 254ldapEntryCacheMaxCount, 107ldapEntryCacheMaxSizeKb, 108ldapHost, 108ldapIndices, 109ldapmodify, 255ldapmodrdn, 256ldapNumEntryDbFiles, 109ldapNumIndexDbFiles, 110ldapOperationLimit, 110ldapRepLogFile, 111ldapRepLogRollHours, 111ldapRootDn, 112ldapRootPwd, 112ldapSchemaCheck, 113ldapsearch, 257ldapSizeLimit, 113ldapTimeLimit, 114legalHosts, 114licenseKey, 115licenseWarnThresholdDays, 153ListAccountForwards, 235ListAccounts, 222ListAliases, 237ListCosAttributes, 239ListCosNames, 240ListDomains, 213listenBacklog, 116lockTimeout, 117logDir, 117loginDefaultDomain, 118loginDefaultDomainTable, 119loginFilter, 120loginNameConvertFrom, 121loginNameConvertTo, 121logMailBoxCreation, 122logNamedPipeMode, 122logRecorderSize, 123logToSystem, 123

MM_CreateAlias, 313M_HashPassword, 310M_ReadFolder, 319Mail Delivery Operations, 231Mailbox

C API class, 315mailRoutingHost, 124mailRoutingTable, 125Manager server, 2masterAgentHost, 125



maxAutoReplyMsgLenKb, 126maxBadCommands, 126maxBadPassword, 127maxBadPasswordAddrs, 127maxBadPasswordDelay, 128maxBadPasswordUsers, 128maxBounceNotices, 129maxDirectDelivery, 129maxDirectKB, 130maxFolders, 130maximumMtaHops, 131maxMessageSizeInKB, 132maxMsgTextCache, 132maxMssDeliverCount, 133maxNullSenderRCPTs, 133maxPasswordFailures, 134maxQueueTimeInHours, 135maxSessions, 136maxThreads, 136Message

C API class, 320Message File system, 2Message flow, 2Message Store database, 2Message Store Server, 1Message Transport Agent, 1messageFilesDir, 137messageReadTracing, 137messageTracing, 138mgrServPort, 138mimeParseMode, 139minFreeDiskSpaceInKB, 139minQueueIdleTime, 140ModifyAccount, 223ModifyAccountPop, 225ModifyAccountSmtp, 225ModifyCosAttribute, 240moveRetrieveErrors, 141MsAlreadyExists, 533MsAlreadyPopLocked, 533MsBadBounceNoticeParm, 534MsBadDbname, 534MsBadMS, 534MsBadMssStatistic, 535MsBadQuery, 535MsBadStatistic, 535MsBadURL, 536MsBroadcastFail, 536MsBucketPathTooLong, 537MsCorruptStoresDict, 537MsDeleteMSFail, 538

MsDeliverFolderNotFound, 538MsDuplicateName, 538MsEmpty, 539MsEmptyBucketsFile, 539MsEmptyFolderNotSupp, 540MsEmptyMSName, 540MsFolderLoop, 540MsFolderNotInFolder, 541MsFolderNotMovable, 541MsFolderNotRemovable, 542MsFolderNotRenamable, 542MsFullBucket, 543MsgAttrGFS, 558MsgBadContentLength, 559MsgBadEnclEncode, 559MsgBadHeaderAttr, 560MsgBadHexOid, 560MsgCloseEnclFail, 560MsgCreateEnclFail, 561msgDelivererNumThreads, 141MsgEnclBadCharSeq, 561MsgEnclGFS, 562MsgEnclReadOnly, 562msgFileCacheSizeInKB, 142MsgImpConnLost, 562MsgImpNotaMsg, 563MsgImpOpenDir, 563MsgImpOpenFail, 563MsgImpRemoteErr, 564MsgImpStatFail, 564MsgMoveFail, 565MsgMoveSuccess, 565MsgMPSI, 564MsgMPSO, 565MsgMultiPartNoBoundary, 566MsgNullMsg, 566MsgOidTooLong, 566MsgOpenEnclFail, 567MsgPartialNoId, 567MsgPrematureEndOfFile, 568MsgReadEnclFail, 568MsgSeekEnclFail, 569MsgStatEnclFail, 569MsgTrace, 570msgValidatorNumThreads, 142MsgWriteToInetCalled, 570MsInitFailure, 543MsInvalidMsgFlag, 544MsInvalidObjRef, 544MsKeywordTooLong, 544MsLimitMsgSize, 545

Index


MsLimitNumMsgs, 545MsLimitTotalSize, 546MsLoadedByOtherMSS, 546MsMailboxCreated, 547MsMissingDbname, 547MsMissingObject, 547MsMsgBadFormat, 548MsMsgCreated, 548MsMsgDeleted, 548MsMsgIDNotFound, 549MsMsgLocked, 549MsMsgNotInFolder, 549MsMsgNotLocked, 550MsMsgRangeRead, 550MsMsgRead, 551MsNoAllowDeliver, 551MsNoRight, 552MsNotAFolderRef, 553MsNotAMsgRef, 553MsNotASearchRef, 553MsNotFound, 554MsNoUnlockedMsgs, 552MsNoWelcomeMsg, 552MsNullFolderName, 554MsObjectLocked, 554MsObjectLockedByServer, 555MsOpNotSupported, 555MsPropertyNotSupported, 555MsRestrictedToRoot, 556mssBasePort, 143mssDeliverTimeoutSecs, 143MsSearchOpNotSupported, 556MsUnknownObjType, 556MsUnknownProperty, 557MsUnsupportedQuery, 557MsWrongMS, 557MsWrongObjectType, 558MtaAuthFailBadPswd, 570MtaAuthFailBadUser, 571MtaAutoReplySuppressedAlreadySent, 571MtaAutoReplySuppressedNotInHeader, 571MtaAutoReplySuppressedSender, 572MTABadControlFile, 572MtaBodyFileMoveFailed, 573MtaBodyFileReadFailed, 573MtaBodyFileWriteFailed, 574MtaControlFileBadValue, 574MtaControlFileMoveFailed, 575MtaControlFileReadFailed, 575MtaControlFileWriteFailed, 575MTADeferDirReadFail, 576

MTADeferredFileMoveFail, 576MTADirCacheDown, 577MtaDomainTableLoadFailed, 577MtaDomainTableNotLoaded, 577MtaDomainTableUpdateFailed, 578MtaErrorTrace, 578MtaHeaderFileMoveFailed, 579MtaHeaderFileReadFailed, 579MtaHeaderFileWriteFailed, 580MtaHeaderNotTerminated, 580MtaHeaderRewriteFailed, 580MtaHostInvalid, 581MtaMaxMTAHopCountExceeded, 581MtaMessageQueueDirMismatch, 582MtaMessageQueuedTooLong, 582MtaMessageReturnSuppressed, 583MtaMessageSecureFailed, 583MtaMessageSenderNotAuth, 584MtaMessageTooLarge, 584MTAMsgNoRecipients, 585MtaPathPrefixInvalid, 585MtaQueueDirRemoved, 585MtaQueueServerIterationMismatch, 586MtaRecipientsRejected, 587MtaRouteTableEntryError, 587MtaSenderRejected, 587MtaServerBadReply, 588MtaServerConnectFailed, 588MtaServerDNSALookupFailed, 588MtaServerDNSMXLookupFailed, 589MtaServerFailed, 589MtaServerSocketClosed, 589MtaServerTimedOut, 590MtaServiceNotAllowed, 590MtaServiceNotAllowedSSL, 590MtaSidelineNullToMany, 591MtaSidelineTooManyRCPTs, 591mtaSpool, 144mutexSerialNumbering, 144

NnearQuotaNotice, 145netTimeout, 146NioAcceptFail, 592NioBadPortNumber, 593NioBadQueryCode, 593NioBindFail, 593NioBindLocalFail, 594NioBindNameFail, 594NioCloseSockFail, 595NioConnectionLimitTableBadEntry, 597



NioConnectReadFail, 597NioConNotAllowed, 595NioConnServerFail, 596NioConnTimeout, 596NioCreateSocketFail, 598NioEventNotSupported, 598NioFcntlFail, 599NioFileNameTooLong, 599NioFillQuit, 599NioFindHostNameFail, 600NioGetPortNumberFail, 600NioListenFail, 601NioMaxConnections, 601NioNoPortNumberFound, 601NioPermissionErr, 602NioPollBadReturn, 602NioPollErr, 603NioPollFail, 603NioPrivilegedPortNumber, 603NioReadSocketFail, 604NioRecvError, 604NioRecvFail, 604NioSelectTimeOut, 605NioServerGoneDown, 605NioSetBufferSizeFail, 606NioSetMaxFdsFail, 606NioSetNoDelay, 607NioSetsockoptError, 607NioSocketClosed, 607NioSocketFail, 608NioSocketOpen, 608NioStaleFileErr, 608NioStatFail, 609nlsDir, 146noLocalDelivery, 153numMboxDbFiles, 147numMsgIdDbFiles, 148numUserDBFiles, 148

OoutboundDeferProcessInitialWait, 149outboundDeferProcessInterval, 149

PParmNotOption, 609ParmUnknownOption, 610Perl API, 347, 427pidDir, 150POP server, 1pop3Port, 150

PopCommunicationErr, 610PopConnectionNotAllowed, 611PopConnMade, 611PopConnTimedOut, 611PopDomainTableEntryError, 612popLockIdleTimeout, 153PopLockTimeoutTooAggressive, 612PopMaxSessions, 614PopNoMSS, 614PopProtocolErr, 615popProxyHost, 151PopProxyLoopDetected, 615popProxyPort, 152PopSyncError, 616ProcAssertFail, 616ProcBadStateCode, 617ProcBail, 617ProcBroadcastingCond, 618ProcCantGetProgPath, 618ProcCantKillProcess, 618ProcCantReadPidFile, 619ProcCantReExecProg, 619ProcCatNoName, 619ProcChdirFail, 620ProcChmodFail, 620ProcChownFail, 621ProcCloseFail, 621ProcCondMutexNotLocked, 622ProcConfigChange, 623ProcDeleteLockedMutex, 624ProcDestroyCondFail, 625ProcDestroyMutexFail, 626ProcDupFailed, 626ProcDupSurprise, 627ProcExcStackOvfl, 627ProcExit, 627ProcExitCode, 628ProcFatalSignal, 628ProcFchownFail, 629ProcGetgrnamFail, 629ProcGetpwnamFail, 630ProcGetpwuidFail, 630ProcGetThrdPriFail, 630ProcGetThrdSpecFail, 631ProcInitCondFail, 631ProcInitMutexFail, 632ProcJoinThrdFail, 632ProcKillThrdFail, 633ProcLaunchReport, 633ProcLockAcqOrder, 633ProcLockMutexFail, 634

Index


ProcMTNotSupported, 634ProcMutexWasntLocked, 634ProcNoCHFnd, 635ProcNoFrmwrk, 635ProcNoRunDir, 635ProcNullMutex, 636ProcPipeCreateFailed, 636ProcPoolResourecesLost, 636ProcProcessNotRunning, 637ProcReAcqLockFail, 637ProcReExecingProg, 637ProcSemBadKey, 638ProcSemCreateFail, 638ProcSemGetStatFail, 639ProcSemNoName, 639ProcSemPostFail, 640ProcSemUninitialized, 640ProcSemWaitFail, 641ProcSetgidNum, 641ProcSetMaxPthreadsFail, 642ProcSetThrdPriFail, 642ProcSetThrdSpecFail, 642ProcSetThreadCapabilityFailed, 643ProcSetuidNum, 643ProcSetuidSucceed, 644ProcShutdown, 644ProcShutdownInProgress, 645ProcShutdownPreempted, 645ProcShutdownRequested, 645ProcShutdownSequenceError, 646ProcShutdownStalled, 646ProcSignalCondFail, 647ProcSignalled, 647ProcSuspThrdFail, 647ProcThrdAttrDestroy, 648ProcThrdAttrInitFail, 648ProcThrdKeyCreateFail, 649ProcThrdMainCalled, 649ProcThrdSchedFail, 650ProcThrdSetStacksize, 650ProcTooManyFatals, 651ProcUncaughtCPlusPlusException, 651ProcUnlockMutexFail, 651ProcWaitOnCondFail, 652ProcWriteToStderr, 652

QqueueSplitFactor, 152

RrcptHarvesterCount, 153RcptHarvesterDropped, 592record type

ChangeType, 250Comment, 251Context, 248COS_Assign, 249Default, 250IM_Type, 247Option, 249

rejectDnsServer, 155rejectInvalidFromAddr, 155rejectSenderBadAddress, 153rejectSenderBadDomain, 156rejectSenderIpDomain, 157rejectSenderNoDomain, 157relative distinguished names

modification of, 256relayDestAllowList, 158relayDestDenyList, 158relayHost, 159relayLocalDomainsOk, 159relayLocalMustExist, 160relayNullRestricted, 162relayReplyCode, 162relayReplyText, 163relaySourceDomainList, 163relaySourceLocalIpList, 164relaySourcePolicy, 165relaySourceRemoteIpList, 166Reply

C API class, 323reportParamsInterval, 166requireCrLf, 167rewriteDomains, 168rewriteGatewayHeaderList, 168rewriteHeaderList, 169rewriteMaxMtaHops, 169rewriteOnlyLocal, 170rewritePrimary, 170rewriteSaveOrig, 171rmeAccessList, 171RmeBadClientRef, 653RmeBadDirCacheHost, 653RmeBufferOverrun, 654RmeClientTimeout, 654RmeClientTimeout2, 654RmeConnectionUnavailable, 655rmeConnectTimeout, 172RmeDirCacheDown, 655



RmeDirCacheup, 655RmeFillError, 656RmeNoHostName, 656RmeNullDest, 656RmeOpNotSupported, 657RmeProtoBadDataFmt, 658RmeProtoBadLength, 658RmeProtocolErr, 659RmeProtocolMismatch, 659RmeServerClosedSocket, 660RmeStaleRef, 660RmeUnbindWithNoBind, 661RmeUnexpectedReturn, 661RmeUnexpectedReturn2, 662RmtBadExitStatus, 662RmtChildFstatFail, 662RmtCommandTrace, 663RmtContradictoryVerbsError, 663RmtDidntDie, 663RmtDupFailed, 664RmtDupSurprise, 664RmtExecFailed, 664RmtForkFailed, 665RmtIllegalHost, 665RmtPipeCreateFailed, 665RmtProcessSignalled, 666RmtRMEFailed, 666RmtRMESucceeded, 666RmtStartingRME, 667RmtWaitpidTimeout, 667rolloversPerDay, 172rolloverTimeZero, 173runDir, 174RunPopLockedExclusive, 667

SscanOldMessagesIntervalInHours, 175serverLineLengthLimit, 175serverThreadStackSizeInKB, 176serverTimeout, 176serverTotalLinesLimit, 177servWarnToStderr, 177SetAccountCos, 226SetAccountQuota, 227SetAccountStatus, 228SetAutoReply, 228SetAutoReplyHost, 229SetCosAttribute, 241SetPassword, 230SetProxyHosts, 230SetWildcardAccount, 214

sharedDir, 178ShowCos, 241sidelineMessages, 178sidelineNullToMany, 179sidelineNumRcpts, 179sidelineNumRcptsPerConnection, 180SIEVE, 98sitestartup.batch file, 244sitestartup.install file, 244SMTP Alias Operations, 235smtpAcceptNumThreads, 180SmtpAddressFixed, 668SmtpBadRelayPolicy, 668SmtpClientGreetResponse, 669SmtpClientLineTooLong, 669SmtpClientMailLoopDetected, 670SmtpClientNoGreeting, 670SmtpClientNoResponse, 671SmtpClientResponse, 671SmtpConnectionClosed, 672SmtpConnectionDropped, 672SmtpConnectionDroppedRCPT, 673SmtpConnectionReceived, 673SmtpConnectionTimeout, 674smtpDeliverNumThreads, 181SmtpDnsBadConfig, 674SmtpDnsLookupFailed, 674SmtpDnsLookupTimedOut, 675SmtpDomainNameUnknown, 675SmtpHostNotFound, 675SmtpIllegalUserName, 676SmtpMessageCommitToDiskFailed, 676SmtpMessageDeferFileStuck, 677SmtpMessageNoSpace, 677SmtpMessageTooBig, 678SmtpNameTooLong, 678smtpPort, 181SmtpProtocolNotSupported, 679smtpQueueBucketCount, 182SmtpQueueProcess, 679smtpQueueProcessNumThreads, 182SmtpRecipientRejectedSenderNull, 679SmtpRelayPrevented, 680SmtpSenderAddrInvalid, 680SmtpSenderBlocked, 680SmtpSenderDomainCantVerify, 681SmtpSenderDomainIsIPAddress, 681SmtpSenderDomainMissing, 681SmtpSenderDomainNonexistent, 682SmtpServerBadUsage, 682SmtpServerCommandUnknown, 683

Index


SmtpServerEtrnIssued, 683SmtpServerExpnIssued, 684SmtpServerHackerAlert, 684SmtpServerQsndIssued, 685SmtpServerResponseOverflow, 685SmtpServerTooManyBadCommands, 686SmtpServerVrfyIssued, 686SmtpSidelineMaxRCPTsExceeded, 687SnmpCantConnectToMasterAgent, 687SnmpInitFailed, 688SnmpNoIpAddr, 688snmpReconnectNapTime, 183sslCacheAgeSeconds, 183sslCacheBucketNum, 184sslCertChainPathAndFile, 185sslCertPassword, 185SslConfig, 688SslDBInit, 689SslHandshake, 689sslPop3Port, 186sslSmtpPort, 187SslTLSHandshake, 690sslTrustedCertPathAndFile, 187sslUseSessionCache, 188statNamedPipeMode, 188statRecorderSize, 189subDomains, 189SysHeapCorrupted, 690SysMallocFail, 691SysMSTableFull, 691SysNoSpace, 692

TtimeoutClientData, 190timeoutClientDataDot, 190timeoutClientDataSend, 191timeoutClientGreet, 191timeoutClientHelo, 192timeoutClientMailFrom, 192

timeoutClientQuit, 193timeoutClientRcptTo, 193timeoutClientRset, 194timeoutServerCommand, 194timeoutServerData, 195timeoutServerDelivery, 195timeoutServerDeliveryRejection, 196tmpDir, 196traceNamedPipeMode, 197traceOutputLevel, 197, 198traceRecorderSize, 198traceToStderr, 198trackRcptHarversters, 153trapMask, 199trapQueueSize, 200

UUnsetCosAttribute, 242UnsetWildcardAccount, 215UpdateDomain, 215updateServerDN, 200useBoundThreads, 201useContentDisposition, 201useMmapReads, 202useMmapWrites, 202useMx, 203User records

extracting from InterMail, 242, 244

VvalidatorBatchSize, 203verifyDeferOk, 204verifyRcpts, 205versionConfigDB, 205

WWeb server, 2WelcomeMsgId, 206



Documents

REFERENCE GUIDEdocs.smoe.org/openwave/Kx4.2/Kx42ref.pdfThis manual is organized as follows: • Chapter 1, System Overview, provides an overview of the InterMail Mx system. • Chapter