R E F E R E N C E
G U I D E
Version 4.2
Published November, 1999
Software.com, Inc.
www.software.com
525 Anacapa Street
Santa Barbara, CA 93101-1603
Tel: (805) 882-2470
Fax: (805) 882-2473
10 Maguire Road, Suite 400
Lexington, MA 02421-3130
Tel: (781) 274-7000
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
Table of Contents
Preface .......................................................................................................... vii
1: System Overview ....................................................................................... 1
InterMail Servers..................................................................................................................1
InterMail Data Storage.........................................................................................................2
Message Flow Through the InterMail System .....................................................................2
2: Configuration Keys.................................................................................... 5
Sample Configuration Key...................................................................................................5
InterMail Servers and Processes....................................................................................6
Impact of Configuration Key Changes..........................................................................8
InterMail Configuration Keys..............................................................................................8
3: Directory Management Utilities ............................................................ 207
imdbcontrol ......................................................................................................................207
imdbcontrol Syntax ...................................................................................................208
Available imdbcontrol Operations ............................................................................209
Domain Operations....................................................................................................211
CreateDomain (cd) ....................................................................................................211
Account Operations ...................................................................................................216
Mail Delivery Operations ..........................................................................................231
SMTP Alias Operations.............................................................................................235
Class-of-Service Operations......................................................................................237
imbatchextract..................................................................................................................242
imbatchextract Syntax ...............................................................................................242
Creating a Targeted User Batch File .........................................................................244
imbatchload......................................................................................................................244
imbatchload Syntax ...................................................................................................244
imbatchload Input File...............................................................................................245
Input File Record Types ............................................................................................247
imintegcheck ....................................................................................................................251
imintegcheck Syntax ................................................................................................252
imintegcheck Operations ...........................................................................................252
ldapadd .............................................................................................................................253
ldapdelete .........................................................................................................................254
ldapmodify .......................................................................................................................255
ldapmodrdn ......................................................................................................................256
ldapsearch.........................................................................................................................257
4: General Administration Utilities ........................................................... 259
Command Descriptions....................................................................................................259
5: InterMail C API........................................................................................ 295
Introduction......................................................................................................................295
Naming Conventions........................................................................................................295
Confidential and Proprietary, © Software.com, Inc. 1999
iii
InterMail Kx Reference Guide
Function Semantics ..........................................................................................................296
Calling Conventions.........................................................................................................296
Library Initialization..................................................................................................296
Object Data Types .....................................................................................................297
Overview of Types...........................................................................................................298
Errors................................................................................................................................299
String Arrays ....................................................................................................................301
Domains ...........................................................................................................................301
Accounts...........................................................................................................................305
Mailboxes.........................................................................................................................315
Folders..............................................................................................................................317
Messages ..........................................................................................................................320
Reply ................................................................................................................................323
Class of Service................................................................................................................325
Configuration Information ...............................................................................................329
MIME Information...........................................................................................................330
Log Messages...................................................................................................................335
Log Context......................................................................................................................337
Compiling, Linking, and Running ...................................................................................340
Sun Microsystems Solaris 2.5.1 and 2.6....................................................................340
Digital UNIX .............................................................................................................341
Silicon Graphics IRIX 6 ............................................................................................341
File Summary...................................................................................................................341
Function Summary...........................................................................................................342
6: InterMail Perl API ................................................................................... 347
Introduction......................................................................................................................347
General Usage Notes .................................................................................................348
Hooking Classes in Your Scripts...............................................................................348
Underlying Libraries and Versioning........................................................................349
Error Handling...........................................................................................................350
Classes and Objects ...................................................................................................350
SwCom::Error Class Reference .......................................................................................352
SwCom::WebSession Class Reference............................................................................352
SwCom::Mail Class Reference ........................................................................................354
CosAttribute ..............................................................................................................354
Cos.............................................................................................................................356
Domain ......................................................................................................................359
Account......................................................................................................................363
Mailbox......................................................................................................................373
Folder.........................................................................................................................377
Message .....................................................................................................................381
Reply..........................................................................................................................385
ConfigItem.................................................................................................................387
MimeInfo...................................................................................................................388
LogMsg......................................................................................................................390
LogContext ................................................................................................................391
iv
Confidential and Proprietary, © Software.com, Inc. 1999
Table of Contents
7: InterManager Perl API............................................................................ 393
Introduction......................................................................................................................393
Overview of Classes.........................................................................................................393
InterManager Perl API Classes ........................................................................................394
SwCom::Error............................................................................................................394
SwCom::WebSession ................................................................................................395
SwCom::IMgr::Session .............................................................................................396
SwCom::IMgr::Entry.................................................................................................398
SwCom::IMgr::Root..................................................................................................401
SwCom::IMgr::Org ...................................................................................................401
SwCom::IMgr::OrgUnit ............................................................................................405
SwCom::IMgr::Person...............................................................................................408
SwCom::IMgr::MailGroup........................................................................................413
SwCom::IMgr::MailTemplate...................................................................................416
SwCom::IMgr::MailCOS ..........................................................................................418
SwCom::IMgr::Provider............................................................................................421
SwCom::IMgr::AdminGroup ....................................................................................424
SwCom::IMgr::Domain.............................................................................................425
8: LDAP Perl API ........................................................................................ 427
Error-Processing Function ...............................................................................................428
ldap_err2string(rc).....................................................................................................428
Connection Management Functions.................................................................................428
ldap_open(host, port).................................................................................................428
ldap_simple_ bind_s(ld, login, password).................................................................428
ldap_unbind(ld) .........................................................................................................429
Functions That Perform Operations on Entries................................................................429
ldap_add_s(ld, dn, data) ............................................................................................429
ldap_modify_s(ln,dn, data)........................................................................................430
ldap_delete_s(ld, dn) .................................................................................................430
ldap_modrdn_s(ld, dn, newrdn) ................................................................................431
ldap_rename_s(ld, dn, newrdn, newbase, deleteold).................................................431
ldap_search_s(ld, dn, scope, filter, attrs, attrsonly, result) ........................................432
ldap_count_entries(ld, result) ....................................................................................432
ldap_get_all_entries(ld, result) ..................................................................................433
Access Control Information Function..............................................................................433
ldap_apply_aci_rule_s...............................................................................................433
Memory Management Function.......................................................................................434
ldap_msgfree(result)..................................................................................................434
9: Log Events.............................................................................................. 435
Account Log Events.........................................................................................................436
Configuration Log Events................................................................................................447
Database Log Events........................................................................................................469
Directory Cache Log Events ............................................................................................483
Filter Log Events..............................................................................................................483
File Input/Output Log Events ..........................................................................................487
IMAP Log Events ............................................................................................................502
Confidential and Proprietary, © Software.com, Inc. 1999
v
InterMail Kx Reference Guide
LDAP Log Events............................................................................................................508
Message Store Log Events...............................................................................................533
Message (Mail) Log Events .............................................................................................558
MTA Log Events .............................................................................................................570
Network Input/Output Log Events...................................................................................592
Parameter Log Events ......................................................................................................609
POP Server Log Events....................................................................................................610
Process Log Events ..........................................................................................................616
RME Log Events..............................................................................................................653
Remote Control Server Log Events .................................................................................662
SMTP Log Events............................................................................................................668
SSL Log Events ...............................................................................................................688
System Log Events...........................................................................................................690
A: Configuration Keys by Server.............................................................. 693
Common Configuration Keys ..........................................................................................693
MTA Configuration Keys ................................................................................................695
MSS Configuration Keys .................................................................................................700
Directory Server Configuration Keys ..............................................................................702
POP Server Configuration Keys ......................................................................................703
IMAP Server Configuration Keys....................................................................................704
Configuration Server Configuration Keys .......................................................................705
Manager Server Configuration Keys ...............................................................................705
SNMP Server Configuration Keys...................................................................................705
B: Supported RFCs .................................................................................... 707
C: License Information .............................................................................. 709
Glossary...................................................................................................... 717
Index............................................................................................................ 739
vi
Confidential and Proprietary, © Software.com, Inc. 1999
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 Audience
This guide assumes that you have a technical background as well as a working
knowledge of the Internet and high-end system issues.
Organization
This manual is organized as follows:
•
•
Chapter 1, System Overview, provides an overview of the InterMail Mx system.
•
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 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.
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 7, InterManager Perl API, provides descriptions of the InterManager Perl
API classes.
Appendix A, Configuration Keys by Server, groups configuration keys according
to the servers they control.
Confidential and Proprietary, © Software.com, Inc. 1999
vii
InterMail Kx Reference Guide
•
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
imdbcontrol command
• Directory and file names
cron utility
• Hostnames
Set this key to true.
• Configuration keys and
their values
• Utility names
<angle brackets> in a
A required variable
imboxget <address>
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
A list of options, one of which
is required
immsgdelete {<msgID>...|-all}
command
... (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
command
[square brackets] in a
command
viii
Confidential and Proprietary, © Software.com, Inc. 1999
Preface
Related Documentation
This 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 Comments
Your feedback is important to us! To suggest improvements or make comments on the
content of this manual, please send e-mail to InterMail.Manual@Software.com.
Confidential and Proprietary, © Software.com, Inc. 1999
ix
InterMail Kx Reference Guide
x
Confidential and Proprietary, © Software.com, Inc. 1999
1
System 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 Servers
The 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 that contains addressing errors or appears to be spam is held for
administrator review.
Mail destined for remote users is passed to the appropriate remote mail
server.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
1
InterMail Kx Reference Guide
•
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 Storage
The 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 System
The individual InterMail components work together to facilitate mail delivery and
retrieval.
2
Confidential and Proprietary, © Software.com, Inc. 1999
8
System Overview
POP Server
IMAP Server
Web Server
Figure 1 illustrates message and communications flow through a sample InterMail
system. The large rectangle
the IMAP
InterMail
Solid
lines
POP portrepresents
110
port 143host machine.
HTTP
port 80
represent message flow. Broken lines indicate communication between system
7
10
7
10
7
10
components.
Note:
Figure 1
The servers dedicated to
managing
the InterMail
system do not WebMail
appear Client
in this
POP
Client
IMAP Client
diagram since they do not play a direct role in message
flow.c
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:
–
–
–
–
–
–
6.
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
3
InterMail Kx Reference Guide
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.
4
Confidential and Proprietary, © Software.com, Inc. 1999
2
Configuration 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 Key
The 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.
Confidential and Proprietary, © Software.com, Inc. 1999
5
InterMail Kx Reference Guide
FRQILJ.H\1DPH
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]
InterMail Servers and Processes
Each 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]
6
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
The InterMail servers and their corresponding server process names are as follows:
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
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]
Confidential and Proprietary, © Software.com, Inc. 1999
7
InterMail Kx Reference Guide
Impact of Configuration Key Changes
The 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 Keys
The 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.
8
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VHUYHU!BRSW
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]
VHUYHU!BUXQ
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
Servers Affected:
all servers
Change Impact:
Warning! Do not attempt to modify the value of this key.
Possible Values:
on or off
Initial Value:
set during installation
Default Value:
off
Example:
/paris/sysadmin/mta_run: [on]
Confidential and Proprietary, © Software.com, Inc. 1999
9
InterMail Kx Reference Guide
DERUW,I/RJ)DLOV
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/abortIfLogFails: [false]
DGPLQ0HVVDJH6WRUH1DPH
10
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DGPLQ3RUW
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
set during installation
Default Value:
null
Example:
/paris/imconfserv/adminPort: [5001]
DGYHUWLVH3URGXFW
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
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/advertiseProduct: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
11
InterMail Kx Reference Guide
DOORZHG,3V
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: []
DOORZ(WUQ
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.
12
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/allowEtrn: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DOORZ([SQ
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/allowExpn: [false]
DOORZ+HOS
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/allowHelp: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
13
InterMail Kx Reference Guide
DOORZ4VQG
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/allowQsnd: [true]
DOORZ7/6
14
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
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
false or true
Initial Value:
false
Default Value:
false
Example:
/*/mta/allowTLS:[false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DOORZ9UI\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/allowVrfy: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
15
InterMail Kx Reference Guide
DOZD\V4XHXH
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.
16
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/alwaysQueue: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DOZD\V7U\)LUVW
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, additional messages for such domains will be added to the existing
queues and held until the next deferred mail processing interval. Use of this setting conserves system resources by limiting
delivery attempts to domains whose mail host may be temporarily out of service.
•
If the value of alwaysTryFirst is set to true, InterMail
will always attempt immediate message delivery of all messages. A message will be added to a queue only after InterMail 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. However, if mail is already queuing for a domain and that domain
name is not listed among the values for the alwaysTryFirstList key, InterMail will simply add the message to the
existing queue without attempting immediate delivery.
Confidential and Proprietary, © Software.com, Inc. 1999
17
InterMail Kx Reference Guide
•
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.
18
Related Keys:
alwaysTryFirstList
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true, false, allowlisted, denylisted
Initial Value:
false
Default Value:
false
Example:
/*/mta/alwaysTryFirst: [allowlisted]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DOZD\V7U\)LUVW/LVW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a list of domains
Initial Value:
null
Default Value:
null
Example:
/*/mta/alwaysTryFirstList: [software.com]
[hardware.com]
Confidential and Proprietary, © Software.com, Inc. 1999
19
InterMail Kx Reference Guide
DXWR5HSO\&KDUVHW
Description:
Character set that auto-reply messages use.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
us-ascii
Initial Value:
us-ascii
Default Value:
us-ascii
Example:
/*/mta/autoReplyCharset: [us-ascii]
DXWR5HSO\'HIDXOW0HVVDJH
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 accountspecific 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.
20
Related Keys:
autoReplyCharset
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
a text string
Initial Value:
null
Default Value:
no autoreply message defined
Example:
/*/mss/autoReplyDefaultMessage: [hello]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
DXWR5HSO\([SLUH'D\V
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
null
Default Value:
7
Example:
/*/mss/autoReplyExpireDays: [7]
Confidential and Proprietary, © Software.com, Inc. 1999
21
InterMail Kx Reference Guide
DXWR5HSO\6XSSUHVV/LVW
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
listserv@software.com, listserv@accordance.com, or
listserv@anydomain.com).
autoReplySuppressList may include multiple entries, but each
entry must appear on a separate line between its own set of square
brackets.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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
22
Default Value:
null
Example:
/*/mta/autoReplySuppressList:
[listserv]
[echo]
[list.manager]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EDFNXS0RGH
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
Initial Value:
false
Default Value:
false
Example:
/*/mss/backupMode: [false]
EDG3DVVZRUG'HOD\
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 reauthentication attempts when the user submits a bad password.
Related Keys:
maxBadPasswordDelay
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
5
Default Value:
5
Example:
/*/common/badPasswordDelay: [5]
Confidential and Proprietary, © Software.com, Inc. 1999
23
InterMail Kx Reference Guide
EDG3DVVZRUG:LQGRZ
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
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
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]
ELQ'LU
24
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EORFN$GGUHVVHV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockAddresses: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
25
InterMail Kx Reference Guide
EORFN&RQQHFWLRQV
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).
Note: The blockPerAccount configuration key further restricts
the application of blocking policies.
26
Related Keys:
blockTheseIPs, blockPerAccount
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockConnections: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EORFN'RPDLQV
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 ).
Note: The blockPerAccount configuration key further restricts
the application of blocking policies.
Related Keys:
blockTheseDomains, blockPerAccount
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockDomains: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
27
InterMail Kx Reference Guide
EORFN/RFDO1R$FFW
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.
Note: The blockPerAccount configuration key further restricts
the application of blocking policies.
28
Related Keys:
blockPerAccount
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockLocalNoAcct: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EORFN3HU$FFRXQW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockPerAccount: [false]
EORFN5HSO\&RGH
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer from 400 to 599
Initial Value:
550
Default Value:
550
Example:
/*/mta/blockReplyCode: [550]
Confidential and Proprietary, © Software.com, Inc. 1999
29
InterMail Kx Reference Guide
EORFN5HSO\7H[W
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a text string
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.]
EORFN7KHVH$GGUHVVHV
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.
30
Related Keys:
blockAddresses
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid e-mail address
Initial Value:
null
Default Value:
null
Example:
/*/mta/blockTheseAddresses:
[get.rich@scam.com]
[make.money@bogus.com]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EORFN7KHVH'RPDLQV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
31
InterMail Kx Reference Guide
EORFN7KHVH,3V
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.
32
Related Keys:
blockConnections
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid IP address
Initial Value:
null
Default Value:
null
Example:
/*/mta/blockTheseIPs:
[10.3.21.0]
[21.5.117.4]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
EORFN7KHVH8VHUV
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 big.bucks@scam.com, big.bucks@software.com,
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
33
InterMail Kx Reference Guide
EORFN8VHUV
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 ).
Note: The blockPerAccount configuration key further restricts
the application of blocking policies.
Related Keys:
blockTheseUsers, blockPerAccount
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/blockUsers: [false]
ERG\'DWD%XIIHU
34
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
32768
Default Value:
32768
Example:
/*/common/bodyDataBuffer: [32768]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ERXQFH)DLOXUH%RG\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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.]
Confidential and Proprietary, © Software.com, Inc. 1999
35
InterMail Kx Reference Guide
ERXQFH)DLOXUH+HDGHU
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.
36
Related Keys:
bounceFailureBody
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a header (which may include any of the supported macros)
Initial Value:
as indicated in the example below
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ERXQFH2Q4XRWD)XOO
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/bounceOnQuotaFull: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
37
InterMail Kx Reference Guide
ERXQFH4XRWD1RWLFH
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 messages 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
38
Related Keys:
maxBounceNotices
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
a text string (which may include any of the supported macros)
Initial Value:
as indicated in the example below
Default Value:
null
Confidential and Proprietary, © Software.com, Inc. 1999
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.]
Confidential and Proprietary, © Software.com, Inc. 1999
39
InterMail Kx Reference Guide
ERXQFH6XFFHVV%RG\
Description:
Text in the bounce notification sent to indicate bouncing of a
successful delivery status notification (DSN).
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.
bounceSuccessBody may include multiple lines of text, but each
line must be within its own set of square brackets.
40
Related Keys:
bounceSuccessHeader
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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/bounceSuccessBody:
[Content-Type: text/plain]
[]
[<ErrorText>]
[]
[Please reply to Postmaster@<PostmasterDomain>]
[if you feel this message to be in error.]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ERXQFH6XFFHVV+HDGHU
Description:
Header text in the bounce notification sent to indicate bouncing of a
successful delivery status notification (DSN).
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.
bounceSuccessHeader may include multiple lines of text, but
each line must be within its own set of square brackets.
Related Keys:
bounceSuccessBody
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a header (which may include any of the supported macros)
Initial Value:
as indicated in the example below
Default Value:
null
Example:
/*/mta/bounceSuccessHeader:
[To: <ReturnAddress>]
[From: Mail Administrator Postmaster@<Domain>>]
[Reply-To: Mail Administrator
<Postmaster@<Domain>>]
[Subject: Mail System Delivery Report]
EXFNHW&RXQW
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
Servers Affected:
MTA
Change Impact:
Warning! Do not attempt to modify the value of this key.
Possible Values:
any integer greater than zero
Initial Value:
499
Default Value:
499
Example:
/*/mta/bucketCount: [499]
Confidential and Proprietary, © Software.com, Inc. 1999
41
InterMail Kx Reference Guide
FDFKH/LPLW,Q.%
Description:
Maximum size (in kilobytes) of the server’s cache.
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
256
Default Value:
256
Example:
/*/common/cacheLimitInKB: [256]
FDQRQLFDOL]H
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.
42
Related Keys:
defaultDomain
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/canonicalize: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FKHFN$XWKHQWLFDWLRQ
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 nonexistent user. If it is true, you cannot.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/checkAuthentication: [false]
FKHFN3RLQW,QWHUYDO
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
Initial Value:
1
Default Value:
1
Example:
/*/common/checkPointInterval: [1]
seconds
Confidential and Proprietary, © Software.com, Inc. 1999
43
InterMail Kx Reference Guide
FKHFN3RLQW5HWU\,QWHUYDO
44
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
Change Impact:
trivial
Possible Values:
1 - 3600
Initial Value:
1
Default Value:
1
Example:
/*/common/checkPointRetryInterval: [1]
seconds
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FOLHQW&RQQHFWLRQ/LPLW7DEOH
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 emailers 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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
45
InterMail Kx Reference Guide
FOLHQW+HDSV
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.
46
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
Directory server: 16
MTA: 64
MSS: 16
POP server: 32
IMAP server: 32
remaining servers: 16
Default Value:
32
Example:
/*/mta/clientHeaps: [64]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FOLHQW/LQH/HQJWK/LPLW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
1000
Default Value:
1000
Example:
/*/mta/clientLineLengthLimit: [1000]
Confidential and Proprietary, © Software.com, Inc. 1999
47
InterMail Kx Reference Guide
FOLHQW7LPHRXW
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
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
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]
FRPPRQ*URXS
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.
48
Related Keys:
commonUser
Servers Affected:
all servers
Change Impact:
Warning! Do not attempt to modify the value of this key.
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FRPPRQ8VHU
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
Servers Affected:
all servers
Change Impact:
Warning! Do not attempt to modify the value of this key.
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]
FRPSOHWLRQ0HWKRG
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).
Related Keys:
defaultDomain
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
default, bounce, or sender
Initial Value:
default
Default Value:
default
Example:
/*/mta/completionMethod: [default]
Confidential and Proprietary, © Software.com, Inc. 1999
49
InterMail Kx Reference Guide
FRQILJ)LOHV
Description:
The location of the configuration file for LDAP functions in the
Integrated Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
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]
FRQILJ5HFRUGHU6L]H
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:
50
Possible Values:
any non-negative integer (zero disables the recorder buffer).
Initial Value:
10240
Default Value:
10240
Example:
/*/common/configRecorderSize: [10240]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FRQI6HUY+RVW
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any valid host name
Initial Value:
set during installation
Default Value:
null
Example:
*/common/confServHost: [paris]
FRQI6HUY3RUW
Description:
Port number that the Configuration server listens on for connection
requests from other InterMail programs.
Related Keys:
none
Servers Affected:
the Configuration server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
set during installation
Default Value:
0
Example:
/*/imconfserv/confServPort: [5000]
Confidential and Proprietary, © Software.com, Inc. 1999
51
InterMail Kx Reference Guide
FRQI7LPH6WDPS
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.
52
Related Keys:
none
Servers Affected:
all servers
Change Impact:
Warning! Do not attempt to modify the value of this key.
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
FRQYHUW'RPDLQ/LWHUDOV
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, user@10.21.27.5.) 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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/convertDomainLiterals: [true]
FRV0LQ8SGDWH6HFRQGV
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer
Initial Value:
300
Default Value:
300 (5 minutes)
Example:
/*/mss/cosMinUpdateSeconds: [300]
(5 minutes)
Confidential and Proprietary, © Software.com, Inc. 1999
53
InterMail Kx Reference Guide
FUHDWHV0ER[HV
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
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/common/createsMboxes: [true]
GE/RJ)LOH0D[6L]H.E
54
Description:
The maximum size of a database log file. Database log files are
used for recovery from crashes.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer
Initial Value:
64
Default Value:
64
Example:
/*/mss/dbLogFileMaxSizeKb: [64]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
GE0ER[&DFKH6L]HLQ.%
Description:
The size of the in-memory cache for the mbox database.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer
Initial Value:
16
Default Value:
16
Example:
/*/mss/dbMboxCacheSizeinKB: [16]
GE0ER[3DJH6L]HLQ.%
Description:
The page size for the mbox file for the database.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer
Initial Value:
16
Default Value:
16
Example:
/*/mss/dbMboxPageSizeinKB: [16]
Confidential and Proprietary, © Software.com, Inc. 1999
55
InterMail Kx Reference Guide
GE0VJ,G&DFKH6L]HLQ.%
Description:
The size of the in-memory cache for the msgid database.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer
Initial Value:
16384
Default Value:
16384
Example:
/*/mss/dbMsgIdCacheSizeinKB: [16384]
GE0VJ,G3DJH6L]HLQ.%
56
Description:
The page size for the msgid database.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer
Initial Value:
16
Default Value:
16
Example:
/*/mss/dbMsgIdPageSizeinKB: [16]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
GE3DJH6L]H,Q.%
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
Servers Affected:
Directory server
Change Impact:
server restart required
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
Servers Affected:
Directory server
Change Impact:
server restart required
GE6XIIL[
Possible Values:
Initial Value:
null
Default Value:
null
Example:
/*/imdirserv/dbSuffix: [ ]
GE9HUERVH)ODJ
Description:
Cause the database to output more verbose logging information.
Related Keys:
Servers Affected:
MSS
Change Impact:
server restart required
Confidential and Proprietary, © Software.com, Inc. 1999
57
InterMail Kx Reference Guide
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mss/dbVerboseFlag: [false]
GHIDXOW$GPLQ1DPH
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.
58
Related Keys:
none
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any text string
Initial Value:
admin
Default Value:
admin
Example:
/*/mss/defaultAdminName: [admin]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
GHIDXOW'RPDLQ
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid domain name
Initial Value:
null
Default Value:
null
Example:
/*/mta/defaultDomain: [software.com]
GHIDXOW6WDFN6L]H,Q.%
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
64
Default Value:
0
Example:
/*/common/defaultStackSizeInKB: [64]
Confidential and Proprietary, © Software.com, Inc. 1999
59
InterMail Kx Reference Guide
GHIHU2Q0[/RRNXS)DLO
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/deferOnMxLookupFail: [true]
GHIHU3URFHVV,QWHUYDO
60
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
600
Default Value:
600 (10
Example:
/*/mta/deferProcessInterval: [600]
(10 minutes)
minutes)
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
GLU5PH&RQQHFWLRQV
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
Change Impact:
server restart required
Possible Values:
any integer greater than 1
Initial Value:
40
Default Value:
10
Example:
/*/common/dirRmeConnections: [40]
GLU5PH+RVWV
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.
Change Impact:
Trivial
Possible Values:
A colon-separated list of hosts.
Initial Value:
null
Default Value:
null
Example:
/*/common/dirRmeHost: [paris]
Confidential and Proprietary, © Software.com, Inc. 1999
61
InterMail Kx Reference Guide
GLU5PH0D[6HFRQGDU\&DOOV
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
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
100
Default Value:
100
Example:
/*/imdirserv/dirRmeMaxSecondaryCalls: [100]
GLU5PH3RUW
Description:
Port number on which the Directory server listens for requests.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
set during installation
Default Value:
null
Example:
/*/imdirserv/dirRmePort: [5888]
GLU6HUY1DPH
Description:
Establishes a connection between the Mx IMAP server and the Kx
Directory server.
WARNING! Do not modify this key.
62
Related Keys:
none
Servers Affected:
IMAP server
Change Impact:
server restart required
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
Possible Values:
text string which is either imdircacheserv or imdirserv
Initial Value:
imdircacheserv
Default Value:
imdircacheserv
Example:
/*/common/dirServName [imdirserv]
GRPDLQ1DPH
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).
Related Keys:
defaultDomain
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any valid domain name
Initial Value:
the domain name provided during installation
Default Value:
null
Example:
/*/common/domainName: [software.com]
GRPDLQ8SGDWH,QWHUYDO
Description:
Interval (in seconds) at which the MTA requests updated domain
information.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
60
Default Value:
60
Example:
/*/mta/domainUpdateInterval: [60]
Confidential and Proprietary, © Software.com, Inc. 1999
63
InterMail Kx Reference Guide
GURS&RQQHFWLRQV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/dropConnections: [false]
GURS0D[0HVVDJH5&37V
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.
64
Related Keys:
dropConnections
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/dropMaxMessageRCPTs: [100]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
GURS5&37V5HSO\7H[W
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a text string
Initial Value:
service unavailable
Default Value:
service unavailable
Example:
/*/mta/dropRCPTsReplyText: [service unavailable]
GURS7KHVH,3V
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid IP address
Initial Value:
null
Default Value:
null
Example:
/*/mta/dropTheseIPs:
[100.28.56.44]
[10.3.21.0]
Confidential and Proprietary, © Software.com, Inc. 1999
65
InterMail Kx Reference Guide
GXS0HVVDJH'HWHFW
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mss/dupMessageDetect: [true]
HQWU\&DFKH0D[&RXQW
Description:
Maximum number of entries to keep in the cache for the LDAP
Entries database.
Related Keys:
66
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer.
Initial Value:
1000
Default Value:
1000
Example:
/*/imdirserv/entryCacheMaxCount: [1000]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
HQWU\&DFKH0D[6L]H.%
Description:
Maximum size of the cache for the LDAP Entries database.
Related Keys:
Servers Affected:
Directory server
Change Impact:
trivial, no server restart required
Possible Values:
Any non-negative integer (including 0)
Initial Value:
0
Default Value:
0
Example:
/*/imdirserv/entryCacheMaxSizeKB: [0]
(UURU$FWLRQVDFFW,QDFWLYH
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/acctInactive:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
67
InterMail Kx Reference Guide
(UURU$FWLRQVDFFW,QYDOLG8VHU
Description:
Error action the MTA takes when a message arrives for an
unrecognized destination address (for example, an incomplete
address or unknown user).
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.
68
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/acctInvalidUser:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVEDG5HWXUQ
Description:
Error action the MTA takes when it cannot successfully return an
undeliverable message due to a problem with the return address.
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 hold. A null setting means to
defer the message.
Related Keys:
the corresponding Error-Code configuration key
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/badReturn:
[log]
[hold]
and hold
Confidential and Proprietary, © Software.com, Inc. 1999
69
InterMail Kx Reference Guide
(UURU$FWLRQVILOW$FWLRQ%RXQFH
Description:
Error action the MTA takes when a filter for incoming mail
determines that it should not deliver a message.
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.
70
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/filtActionBounce:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPV/LPLW0VJ6L]H
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).
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/msLimitMsgSize:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
71
InterMail Kx Reference Guide
(UURU$FWLRQVPV/LPLW1XP0VJV
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).
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.
72
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/msLimitNumMsgs:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPV/LPLW7RWDO6L]H
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).
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/msLimitTotalSize:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
73
InterMail Kx Reference Guide
(UURU$FWLRQVPV1R$OORZ'HOLYHU
Description:
Error action the MTA takes when a message arrives for a disabled
mailbox.
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.
74
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/msNoAllowDeliver:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD+RVW,QYDOLG
Description:
Error action the MTA takes when a message arrives addressed to an
invalid host (a destination machine the system cannot find).
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaHostInvalid:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
75
InterMail Kx Reference Guide
(UURU$FWLRQVPWD0D[0WD+RS&RXQW([FHHGHG
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.
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 setting is log and hold. A null setting means to
defer the message.
Related Keys:
maximumMtaHops, the corresponding Error-Code configuration
key
76
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMaxMtaHopCountExceeded:
[log]
[hold]
and hold
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD0HVVDJH'HOLYHUHG
Description:
Determines how to handle a "successful delivery" status
notification.
The possible error actions (which you may use independently or in
combination) are as follows:
•
return: Send the delivery status notification
•
hold: Hold the delivery status notification
•
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 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.
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
return
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMessageDelivered: [return]
Confidential and Proprietary, © Software.com, Inc. 1999
77
InterMail Kx Reference Guide
(UURU$FWLRQVPWD0HVVDJH([SDQGHG
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.
The possible error actions (which you may use independently or in
combination) are as follows:
•
return: Send the delivery status notification
•
hold: Hold the delivery status notification
•
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 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.
78
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
return
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMessageExpanded: [return]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD0HVVDJH4XHXHG7RR/RQJ
Description:
Error action the MTA takes when a deferred message has been in
the queue longer than the configured limit set in
maxQueueTimeInHours.
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:
maxQueueTimeInHours, the corresponding Error-Code and
Error-Text configuration keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMessageQueuedTooLong:
[log]
[return]
and return
Confidential and Proprietary, © Software.com, Inc. 1999
79
InterMail Kx Reference Guide
(UURU$FWLRQVPWD0HVVDJH5HMHFWHG
Description:
Error action the MTA takes when the receiving SMTP server
rejects a message.
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 setting is return. A null setting means to defer the
message.
80
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
return
Default Value:
return
Example:
/*/mta/Error-Actions/mtaMessageRejected: [return]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD0HVVDJH5HOD\H
Description:
How to handle delivery status notification for a message relayed to
a machine that does not handle delivery status notification.
The possible error actions (which you may use independently or in
combination) are as follows:
•
return: Send the delivery status notification
•
hold: Hold the delivery status notification
•
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 setting is return. A null setting means to defer the
message.
Related Keys:
the corresponding Error-Code and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
return
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMessageRelayed: [return]
Confidential and Proprietary, © Software.com, Inc. 1999
81
InterMail Kx Reference Guide
(UURU$FWLRQVPWD0HVVDJH7RR/DUJH
Description:
Error action the MTA takes when it rejects a message because that
message is too large (for example, larger than
maxMessageSizeInKb).
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:
maxMessageSizeInKb, the corresponding Error-Code and
Error-Text configuration keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMessageTooLarge:
and return
[log]
[return]
82
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD0VJ1R5HFLSLHQWV
Description:
Error action the MTA takes when it receives a message that does
not include any recipients.
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 hold. A null setting means to
defer the message.
Related Keys:
the corresponding Error-Code configuration key
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaMsgNoRecipients:
and hold
[log]
[hold]
Confidential and Proprietary, © Software.com, Inc. 1999
83
InterMail Kx Reference Guide
(UURU$FWLRQVPWD5HFLSLHQWV5HMHFWHG
Description:
Action the MTA takes when the receiving SMTP server rejects one
or more message recipients.
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaRecipientsRejected:
and return
[log]
[return]
84
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVPWD6HQGHU5HMHFWHG
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).
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:
rejectSenderBadDomain, rejectSenderIPDomain,
rejectSenderNoDomain, and the corresponding Error-Code
and Error-Text configuration keys
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/mtaSenderRejected:
and return
[log]
[return]
Confidential and Proprietary, © Software.com, Inc. 1999
85
InterMail Kx Reference Guide
(UURU$FWLRQVVPWS&OLHQW0DLO/RRS'HWHFWHG
Description:
Error action the MTA takes when it detects a message caught in a
mail loop.
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 hold. A null setting means to
defer the message.
Related Keys:
maximumMtaHops, the corresponding Error-Code configuration
key
86
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/smtpClientMailLoopDetected:
[log]
[hold]
and hold
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU$FWLRQVVPWS'QV%DG&RQILJ
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.
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/smtpDnsBadConfig:
and return
[log]
[return]
Confidential and Proprietary, © Software.com, Inc. 1999
87
InterMail Kx Reference Guide
(UURU$FWLRQVVPWS3URWRFRO1RW6XSSRUWHG
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:
•
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
one or more of the values return, hold, and log
Initial Value:
log
Default Value:
null
Example:
/*/mta/Error-Actions/smtpProtocolNotSupported:
[log]
[return]
and return
(UURU&RGHNH\1DPH!
Description:
Error code returned when the value of the corresponding ErrorAction key is return.
88
Related Keys:
the corresponding Error-Action and Error-Text configuration
keys
Servers Affected:
MTA
Change Impact:
Warning! Do not attempt to modify the value of these keys.
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
(UURU7H[WNH\1DPH!
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
Servers Affected:
MTA
Change Impact:
Warning! Do not attempt to modify the value of these keys.
HYHQW0D[:DLW
Description:
Maximum time (in seconds) a server can wait for any event. After
this period expires, servers will time out.
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
3000
Default Value:
3000
Example:
/*/common/eventMaxWait: [3000]
Confidential and Proprietary, © Software.com, Inc. 1999
89
InterMail Kx Reference Guide
H[WUD&RS\&RQILJ'%3DWK
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.
90
Related Keys:
none
Servers Affected:
Configuration server
Change Impact:
trivial, no server restart required
Possible Values:
any valid file path
Initial Value:
null
Default Value:
null
Example:
/*/imconfserv/extraCopyConfigDBpath:[cfbak]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
IDWDO6LJ+DQGOHUV
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/fatalSigHandlers: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
91
InterMail Kx Reference Guide
ILOH'HVFULSWRUV
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
MTA: 2048
MSS: 2048
POP server: 2048
IMAP server: 2048
remaining servers: 0
Default Value:
0
Example:
/*/mta/fileDescriptors: [2048]
JPW/RJ7LPHV
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.
92
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/gmtLogTimes: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
KRVWQDPH$OLDV/LVW
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.
foo.com.
MX
MX
5 foo.com
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:
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
93
InterMail Kx Reference Guide
LGOH)OXVK7LPHRXW6HFV
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
10
Default Value:
10
Example:
/*/mss/idleFlushTimeoutSecs: [10]
LPDQ/RJLQ
94
Description:
The InterManager login name. This name is specified at time of
installation.
Related Keys:
imanOrg, imanPass, imanUID
Servers Affected:
Directory server
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
LPDQ2UJ
Description:
The name of the initial (site) organization.
Related Keys:
imanLogin, imanPass, imanUID
Servers Affected:
Directory server
Change Impact:
Do not change this value in config.db. A serious error may occur.
Possible Values:
Any alphanumeric string assigned as the initial site organization.
Initial Value:
null
Default Value:
null
Example:
/*/install/imanOrg: [CompanyABC]
LPDQ3DVV
Description:
The password for the InterManager Site Administrator.
Related Keys:
imanLogin, imanOrg, imanUID
Servers Affected:
Directory server
Change Impact:
Do not change this value in config.db. A serious error may occur.
Possible Values:
Any alphanumeric string assigned as the Site Administrator’s
password.
Initial Value:
null
Default Value:
null
Example:
/*/install/imanPass: [admin]
Confidential and Proprietary, © Software.com, Inc. 1999
95
InterMail Kx Reference Guide
LPDQ8,'
Description:
The e-mail address for the InterManager Site Administrator.
Related Keys:
imanLogin, imanOrg, imanPass
Servers Affected:
Directory server.
Change Impact:
Do not change this value in config.db. A serious error may occur.
Possible Values:
The value of imanLogin and the DefaultDomain, set at time of
install.
Initial Value:
null
Default Value:
null
Example:
/*/install/imanUID: [admin@software.com]
LPDS3RUW
96
Description:
Port on which the IMAP server listens for incoming connections.
The standard IMAP port is 143.
Related Keys:
none
Servers Affected:
IMAP server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
143
Default Value:
-1
Example:
/*/imapserv/imap4Port: [143]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
LPER[FRS\1XP7KUHDGV
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
Change Impact:
no impact on server
Possible Values:
any integer greater than zero
Initial Value:
30
Default Value:
30
Example:
/*/mss/imboxcopyNumThreads: [30]
LPER[PLJUDWH1XP7KUHDGV
Description:
Maximum number of threads the imboxmigrate administrative
command can use (unless the command’s -threads option
overrides).
Related Keys:
none
Servers Affected:
MSS
Change Impact:
no impact on server
Possible Values:
any integer greater than zero
Initial Value:
30
Default Value:
30
Example:
/*/mss/imboxmigrateNumThreads: [30]
Confidential and Proprietary, © Software.com, Inc. 1999
97
InterMail Kx Reference Guide
LQFRPLQJ0DLO)LOWHU
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.
98
Related Keys:
blockPerAccount
Servers Affected:
MTA
Change Impact:
server restart required
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";]
[}]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
LQ'HOLYHU\'HIHU.E
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
1000000
Default Value:
1000000
Example:
/*/mta/inDeliveryDeferKb: [1000000]
Confidential and Proprietary, © Software.com, Inc. 1999
99
InterMail Kx Reference Guide
LQ'HOLYHU\5HMHFW.E
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.
100
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/inDeliveryRejectKb: [0]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
LQ'HOLYHU\6WRS'HIHU3URFHVV.E
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/inDeliveryStopDeferProcessKb: [10000]
Confidential and Proprietary, © Software.com, Inc. 1999
101
InterMail Kx Reference Guide
LQGLFHV
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
Servers Affected:
Directory server
Change Impact:
Server restart required
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]
LQLW&OLHQW7LPHRXW
102
Description:
POP client timeout (in seconds) during the initialization. If zero, the
system uses the default client timeout.
Related Keys:
none
Servers Affected:
POP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
240
Default Value:
0
Example:
/*/popserv/initClientTimeout: [240]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
LQVWDOO'LU
Description:
Directory where InterMail is 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:
The install directory specified at installation time.
Default Value:
null
Example:
/*/common/installDir: [/imail/imail]
,QWHU0DLO9HUVLRQ
Description:
Indicates the version of InterMail installed.
Related Keys:
none
Servers Affected:
all
Change Impact:
trivial
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]
Confidential and Proprietary, © Software.com, Inc. 1999
103
InterMail Kx Reference Guide
OGDS$FFHVV/LVW
Description:
A list of hosts that have access to the LDAP server.
Related Keys:
Servers Affected:
Directory server
Change Impact:
Trivial
Possible Values:
A hostname or colon-separated list of hosts.
Initial Value:
null
Default Value:
null
Example:
/*/imdirserv/ldapAccessList: []
OGDS&OLHQW7LPHRXW
Description:
The idle client connection timeout value.
Related Keys:
104
Servers Affected:
Directory server
Change Impact:
Trivial
Possible Values:
0 to 86400
Initial Value:
0
Default Value:
0
Example:
/*/imdirserv/ldapClientTimeout: [0]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OGDS&RQILJ)LOHV
Description:
List of LDAP configuration files to be read and used by the
Directory server.
Related Keys:
Servers Affected:
Directory server.
Change Impact:
Server restart required
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]
OGDS'E(QWU\&DFKH6L]H,Q.%
Description:
Size of the cache to maintain for LDAP Entries database in the
Integrated Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer (in kb)
Initial Value:
16384
Default Value:
16384
Example:
/*/imdirserv/ldapDbEntryCacheSizeInKB: [16384]
Confidential and Proprietary, © Software.com, Inc. 1999
105
InterMail Kx Reference Guide
OGDS'E(QWU\3DJH6L]H,Q.%
Description:
Page size to maintain for the LDAP Entries database in the
Integrated Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer (in kb)
Initial Value:
16
Default Value:
16
Example:
/*/imdirserv/ldapDbEntryPageSizeInKB: [16]
OGDS'E,QGH[&DFKH6L]H,Q.%
106
Description:
Size of the cache to maintain for the LDAP Index database in the
Integrated Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer (in KB)
Initial Value:
16384
Default Value:
16384
Example:
/*/imdirserv/ldapDbIndexCacheSizeInKB: [16384]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OGDS'E,QGH[3DJH6L]H,Q.%
Description:
Page size for the LDAP Index database in the Integrated Services
Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer (in kb)
Initial Value:
16
Default Value:
16
Example:
/*/imdirserv/ldapDbIndexPageSizeInKB: [16]
OGDS(QWU\&DFKH0D[&RXQW
Description:
The maximum number of LDAP entries to cache in memory.
Related Keys:
ldapEntryCacheMaxSizeKb
Servers Affected:
Directory server
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0).
Initial Value:
1000
Default Value:
1000
Example:
/*/imdirserv/ldapEntryCacheMaxCount: [1000]
Confidential and Proprietary, © Software.com, Inc. 1999
107
InterMail Kx Reference Guide
OGDS(QWU\&DFKH0D[6L]H.E
Description:
The maximum amount of LDAP entries to cache in memory,
measured in terms of KB of entry data.
Related Keys:
ldapEntryCacheMaxCount
Servers Affected:
Directory server
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0)
Initial Value:
0
Default Value:
0
Example:
/*/imdirserv/ldapEntryCacheMaxSizeKb: [0]
OGDS+RVW
108
Description:
Name of the host providing LDAP service.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
Server restart required
Possible Values:
Any valid host name.
Initial Value:
null
Default Value:
null
Example:
/*/common/ldapHost: [paris]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OGDS,QGLFHV
Description:
Values defined for LDAP transactions.
Related Keys:
Servers Affected:
Directory server
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]
OGDS1XP(QWU\'E)LOHV
Description:
Number of files to split the LDAP Entries database into on disk.
Related Keys:
ldapNumIndexDbFiles
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any integer equal or greater to 1
Initial Value:
8
Default Value:
8
Example:
/*/imdirserv/ldapNumEntryDbFiles: [8]
Confidential and Proprietary, © Software.com, Inc. 1999
109
InterMail Kx Reference Guide
OGDS1XP,QGH['E)LOHV
Description:
Number of files to split the LDAP Index database into on disk.
Related Keys:
ldapNumIndexDbFiles
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any integer equal or greater to 1
Initial Value:
8
Default Value:
8
Example:
/*/imdirserv/ldapNumIndexDbFiles: [8]
OGDS2SHUDWLRQ/LPLW
110
Description:
The number of allowable LDAP client operations allowed per
connection
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10
Default Value:
10
Example:
/*/imdirserv/ldapOperationLimit: [10]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OGDS5HS/RJ)LOH
Description:
Location of the LDAP replication log file for the Integrated
Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
A file location relative to $INTERMAIL
Initial Value:
null
Default Value:
null
Example:
/*/imdirserv/ldapRepLogFile: []
OGDS5HS/RJ5ROO+RXUV
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
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
Any non-negative integer (including 0).
Initial Value:
1
Default Value:
1
Example:
/*/imdirserv/ldapRepLogRollHours: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
111
InterMail Kx Reference Guide
OGDS5RRW'Q
Description:
The root Distinguished Name (DN) for the server.
Related Keys:
ldapRootPwd
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
a proper DN specification
Initial Value:
Default Value:
[cn=root]
Example:
/*/imdirserv/ldapRootDn: [cn=root]
OGDS5RRW3ZG
Description:
The password for the root entry on the server.
Related Keys:
ldapRootDn
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
a password
Initial Value:
Default Value:
Example:
112
/*/imdirserv/ldapRootPwd: [secret]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OGDS6FKHPD&KHFN
Description:
Determines whether schema checking should be enabled in the
LDAP component of the Integrated Services Directory.
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/imdirserv/ldapSchemaCheck: [false]
OGDS6L]H/LPLW
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
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
500
Default Value:
500
Example:
/*/imdirserv/ldapSizeLimit: [500]
Confidential and Proprietary, © Software.com, Inc. 1999
113
InterMail Kx Reference Guide
OGDS7LPH/LPLW
Description:
The time limit on the search operations in the LDAP component of
the Integrated Services Directory, in seconds.
Related Keys:
ldapSizeLimit
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
3600 (60 minutes)
Default Value:
3600
Example:
/*/imdirserv/ldapTimeLimit: [3600]
OHJDO+RVWV
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
Change Impact:
server restart required
Possible Values:
any valid host name
Initial Value:
all
Default Value:
all
Example:
/*/immgrserv/legalHosts:
[paris]
[jupiter]
[paris]
114
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
OLFHQVH.H\
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.
Servers Affected:
Directory server
Change Impact:
Server restart required
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.
Confidential and Proprietary, © Software.com, Inc. 1999
115
InterMail Kx Reference Guide
OLFHQVH:DUQ7KUHVKROG'D\V
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
Change Impact:
trivial
Possible Values:
1 to INT_MAX
Initial Value:
30
Default Value:
30
Example:
/*/common/licenseWarnThresholdDays: [30]
OLVWHQ%DFNORJ
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.
116
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
5 to 1024
Initial Value:
1024
Default Value:
1024
Example:
/*/common/listenBacklog: [1024]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ORFN7LPHRXW
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
Servers Affected:
POP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
a valid directory path name
Initial Value:
log
Default Value:
log
Example:
/*/common/logDir: [log]
ORJ'LU
Confidential and Proprietary, © Software.com, Inc. 1999
117
InterMail Kx Reference Guide
ORJLQ'HIDXOW'RPDLQ
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.
118
Related Keys:
none
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any valid domain name
Initial Value:
null
Default Value:
null
Example:
/*/common/loginDefaultDomain: [software.com]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ORJLQ'HIDXOW'RPDLQ7DEOH
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 joe@software.com, while a user logging in as
“joe” to IP address 128.123.46.23 would be recognized as
joe@hardware.com.
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
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
119
InterMail Kx Reference Guide
ORJLQ)LOWHU
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/opts
s/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%i
s/^(.*)$/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,
120
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
a string with multiple substitution expressions
Initial Value:
null
Default Value:
null
Example:
/*/imdirserv/loginFilter: [s%xxx%yyy%i]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ORJLQ1DPH&RQYHUW)URP
Description:
List of characters to convert in a login name.
Related Keys:
loginNameConvertTo
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any valid character or characters
Initial Value:
null
Default Value:
null
Example:
/*/common/loginNameConvertFrom: []
ORJLQ1DPH&RQYHUW7R
Description:
Character used to replace characters in a login name that match
those specified in loginNameConvertFrom.
Related Keys:
loginNameConvertFrom
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any valid character or characters
Initial Value:
@
Default Value:
@
Example:
/*/common/loginNameConvertTo: [@]
Confidential and Proprietary, © Software.com, Inc. 1999
121
InterMail Kx Reference Guide
ORJ0DLO%R[&UHDWLRQ
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
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/common/logMailBoxCreation: [true]
ORJ1DPHG3LSH0RGH
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.
122
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
0, 1, or 2
Initial Value:
0
Default Value:
0
Example:
/*/common/logNamedPipeMode: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
ORJ5HFRUGHU6L]H
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.
Servers Affected:
MSS
Change Impact:
Trivial, no server restart required
Possible Values:
Any non-negative integer
Initial Value:
100000
Default Value:
100000
Example:
/*/common/logRecorderSize: [100000]
ORJ7R6\VWHP
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
Servers Affected:
all servers
Change Impact:
Trivial
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/logToSystem: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
123
InterMail Kx Reference Guide
PDLO5RXWLQJ+RVW
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.
124
Related Keys:
mailRoutingTable
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
any valid host name
Initial Value:
null
Default Value:
null
Example:
/*/mta/mailRoutingHost: [firewall.software.com]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PDLO5RXWLQJ7DEOH
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
Servers Affected:
MTA
Change Impact:
server restart required
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]
PDVWHU$JHQW+RVW
Description:
The name of the host designated as the SNMP master agent.
Related Keys:
Servers Affected:
SNMP server.
Change Impact:
Trivial
Possible Values:
Any hostname
Initial Value:
null
Default Value:
null
Example:
/*/common/masterAgentHost: [paris]
Confidential and Proprietary, © Software.com, Inc. 1999
125
InterMail Kx Reference Guide
PD[$XWR5HSO\0VJ/HQ.E
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
Servers Affected:
MTA
Change Impact:
Trivial.
Possible Values:
0 to 1024
Initial Value:
100
Default Value:
100
Example:
/*/mta/maxAutoReplyMsgLenKb: [377]
PD[%DG&RPPDQGV
126
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 3
Initial Value:
10
Default Value:
10
Example:
/*/mta/maxBadCommands: [10]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PD[%DG3DVVZRUG
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
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
3
Default Value:
3
Example:
/*/imapserv/maxBadPassword: [3]
/*/popserv/maxBadPassword: [3]
PD[%DG3DVVZRUG$GGUV
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
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10240
Default Value:
10240
Example:
/*/common/maxBadPasswordAddrs: [10240]
Confidential and Proprietary, © Software.com, Inc. 1999
127
InterMail Kx Reference Guide
PD[%DG3DVVZRUG'HOD\
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
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
90
Default Value:
90
Example:
/*/common/maxBadPasswordDelay: [60]
PD[%DG3DVVZRUG8VHUV
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.
128
Related Keys:
none
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10240
Default Value:
10240
Example:
/*/common/maxBadPasswordUsers: [10240]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PD[%RXQFH1RWLFHV
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer
Initial Value:
20
Default Value:
0
Example:
/*/mss/maxBounceNotices: [3]
PD['LUHFW'HOLYHU\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than 1
Initial Value:
15
Default Value:
15
Example:
/*/mta/maxDirectDelivery: [15]
Confidential and Proprietary, © Software.com, Inc. 1999
129
InterMail Kx Reference Guide
PD['LUHFW.%
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than 1
Initial Value:
100
Default Value:
100
Example:
/*/mta/maxDirectKB: [120]
PD[)ROGHUV
130
Description:
Maximum number of folders allowed within a user’s mailbox.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than 3
Initial Value:
100
Default Value:
100
Example:
/*/mss/maxFolders: [100]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PD[LPXP0WD+RSV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer from 2 to 50
Initial Value:
30
Default Value:
30
Example:
/*/mta/maximumMtaHops: [30]
PD[.H\ZRUG/HQJWK
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
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
255
Default Value:
255
Example:
/*/common/maxKeywordLength: [255]
Confidential and Proprietary, © Software.com, Inc. 1999
131
InterMail Kx Reference Guide
PD[0HVVDJH6L]H,Q.%
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10240
(10 Mb)
Default Value:
10240
(10 Mb)
Example:
/*/mta/maxMessageSizeInKB: [10240]
PD[0VJ7H[W&DFKH
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).
132
Related Keys:
none
Servers Affected:
IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
Warning! Do not attempt to modify the value of this key.
Initial Value:
1048576
Default Value:
1048576
Example:
/*/imapserv/maxMsgTextCache: [1048576]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PD[0VV'HOLYHU&RXQW
Description:
Maximum number of messages to deliver to a MSS in a single
transaction.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
20
Default Value:
20
Example:
/*/mta/maxMssDeliverCount: [20]
PD[1XOO6HQGHU5&37V
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/maxNullSenderRCPTs: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
133
InterMail Kx Reference Guide
PD[3DVVZRUG)DLOXUHV
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.
134
Related Keys:
none
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10
Default Value:
10
Example:
/*/common/maxPasswordFailures: [10]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PD[4XHXH7LPH,Q+RXUV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
Any non-negative integer representing number of hours.
Initial Value:
96
Default Value:
96
Example:
/*/mta/maxQueueTimeInHours: [96]
(4 days)
Confidential and Proprietary, © Software.com, Inc. 1999
135
InterMail Kx Reference Guide
PD[6HVVLRQV
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.
A value of zero means there is no limit.
Related Keys:
none
Servers Affected:
POP server, IMAP server
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/imapserv/maxSessions: [50]
PD[7KUHDGV
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.
136
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
2048
Default Value:
2048
Example:
/*/common/maxThreads: [2048]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PHVVDJH)LOHV'LU
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
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any valid directory path
Initial Value:
set at installation time
Default Value:
null
Example:
/*/mss/messageFilesDir: [msgfiles]
PHVVDJH5HDG7UDFLQJ
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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mss/messageReadTracing: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
137
InterMail Kx Reference Guide
PHVVDJH7UDFLQJ
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
MSS: false
remaining servers: true
Default Value:
MSS: false
remaining servers: true
Example:
/*/mta/messageTracing: [true]
PJU6HUY3RUW
138
Description:
Port on which the Manager server listens for requests to start, drain,
stop, and restart servers.
Related Keys:
none
Servers Affected:
Manager server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
set during installation
Default Value:
null
Example:
/*/immgrserv/mgrServPort: [5004]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PLPH3DUVH0RGH
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
yes, no, true, false, or imap-only
Initial Value:
imap-only
Default Value:
imap-only
Example:
/*/mta/mimeParseMode: [imap-only]
PLQ)UHH'LVN6SDFH,Q.%
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
10000
Default Value:
10000
Example:
/*/mta/minFreeDiskSpaceInKB: [10000]
Confidential and Proprietary, © Software.com, Inc. 1999
139
InterMail Kx Reference Guide
PLQ4XHXH,GOH7LPH
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.
140
Related Keys:
outboundDeferProcessInterval
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
900 (15 minutes)
Default Value:
60 (1 minute)
Example:
/*/mta/minQueueIdleTime: [900]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PRYH5HWULHYH(UURUV
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
Servers Affected:
POP server
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/popserv/moveRetrieveErrors: [true]
PVJ'HOLYHUHU1XP7KUHDGV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
40
Default Value:
10
Example:
/*/mta/msgDelivererNumThreads: [40]
Confidential and Proprietary, © Software.com, Inc. 1999
141
InterMail Kx Reference Guide
PVJ)LOH&DFKH6L]H,Q.%
Description:
Size (in kilobytes) of the message file cache on the MSS.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
100
Default Value:
100
Example:
/*/mss/msgFileCacheSizeInKB: [100]
PVJ9DOLGDWRU1XP7KUHDGV
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.
142
Related Keys:
dirRmeConnections
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
80
Default Value:
10
Example:
/*/mta/msgValidatorNumThreads: [80]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
PVV%DVH3RUW
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.
Servers Affected:
MSS
Change Impact:
Server restart required
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]
PVV'HOLYHU7LPHRXW6HFV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
1200
Default Value:
1200
Example:
/*/mta/mssDeliverTimeoutSecs: [1200]
Confidential and Proprietary, © Software.com, Inc. 1999
143
InterMail Kx Reference Guide
PWD6SRRO
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
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
a valid file path
Initial Value:
spool
Default Value:
spool
Example:
/*/mta/mtaSpool: [spool]
PXWH[6HULDO1XPEHULQJ
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.
144
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/mutexSerialNumbering: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
QHDU4XRWD1RWLFH
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 messages 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
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
a text string (which may include any of the supported macros)
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.]
Confidential and Proprietary, © Software.com, Inc. 1999
145
InterMail Kx Reference Guide
QHW7LPHRXW
Description:
Timeout (in seconds) for network operations.
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
for the imconfget command: 30
for the imconfcontrol: 30
for 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
Servers Affected:
all servers
Change Impact:
no impact on server
Possible Values:
a valid full file path
Initial Value:
nlslib
Default Value:
null
Example:
/*/common/nlsDir: [nlslib]
QOV'LU
146
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
QR/RFDO'HOLYHU\
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
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
false or true
Initial Value:
false
Default Value:
false
Example:
/*/mta/noLocalDelivery: [false]
QXP0ER['E)LOHV
Description:
The number of files used to store the mbox database.
Related Keys:
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer.
Initial Value:
8
Default Value:
8
Example:
/*/mss/numMboxDbFiles: [8]
Confidential and Proprietary, © Software.com, Inc. 1999
147
InterMail Kx Reference Guide
QXP0VJ,G'E)LOHV
Description:
The number of files used to store the msgid database.
Related Keys:
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any non-negative integer.
Initial Value:
8
Default Value:
8
Example:
/*/mss/numMsgIdDbFiles: [8]
QXP8VHU'%)LOHV
Description:
The number of db files to use when splitting the dircache database
($INTERMAIL/db/dircache).
148
Related Keys:
none
Servers Affected:
Directory server
Change Impact:
server restart required
Possible Values:
any non-negative integer (including 0).
Initial Value:
1
Default Value:
1
Example:
/*/imdirserv/numUserDBFiles: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
RXWERXQG'HIHU3URFHVV,QLWLDO:DLW
Description:
Initial amount of time (in seconds) to wait before processing the
queue of mail deferred for external delivery.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/outboundDeferProcessInitialWait: [0]
RXWERXQG'HIHU3URFHVV,QWHUYDO
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than 60
Initial Value:
300
Default Value:
300
Example:
/*/mta/outboundDeferProcessInterval: [300]
Confidential and Proprietary, © Software.com, Inc. 1999
149
InterMail Kx Reference Guide
SLG'LU
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
a valid directory path
Initial Value:
tmp
Default Value:
tmp
Example:
/*/common/pidDir: [tmp]
SRS3RUW
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).
150
Related Keys:
none
Servers Affected:
POP server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
110
Default Value:
110
Example:
/*/popserv/pop3Port: [110]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
SRS/RFN,GOH7LPHRXW
Description:
Maximum number of seconds a socket can hold a pop lock on a
mailbox without any IO to that mailbox.
Related Keys:
lockTimeout
Servers Affected:
MSS
Change Impact:
trivial
Possible Values:
(integer) 0 ... MAX_INT
Initial Value:
240 seconds
Default Value:
90 seconds
Example:
/*/mss/popLockIdleTimeout: [90]
(pop server version)
SRS3UR[\+RVW
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
Servers Affected:
POP server
Change Impact:
trivial, no server restart required
Possible Values:
any valid hostname
Initial Value:
null
Default Value:
null
Example:
/*/popserv/popProxyHost: [jupiter.accordance.com]
Confidential and Proprietary, © Software.com, Inc. 1999
151
InterMail Kx Reference Guide
SRS3UR[\3RUW
Description:
POP port to use for the host specified in popProxyHost.
Related Keys:
popProxyHost
Servers Affected:
POP server
Change Impact:
trivial, no server restart required
Possible Values:
the port on which the POP server on popProxyHost is listening
Initial Value:
110
Default Value:
110
Example:
/*/popserv/popProxyPort: [110]
TXHXH6SOLW)DFWRU
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.
152
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
100
Default Value:
100
Example:
/*/mta/queueSplitFactor: [100]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UFSW+DUYHVWHU&RXQW
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
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
1...INT_MAX
Initial Value:
30
Default Value:
30
Example:
/*/mta/rcptHarvesterCount: [30]
UFSW+DUYHVWHU77/0LQXWHV
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
Servers Affected:
MTA
Change Impact:
tivial
Possible Values:
1...INT_MAX
Initial Value:
60
Default Value:
60
Example:
/*/mta/rcptHarvesterTTLMinutes: [60]
Confidential and Proprietary, © Software.com, Inc. 1999
153
InterMail Kx Reference Guide
UFSW0D[+DUYHVWHUV
Description:
The maximum number of harvesters and potential harvesters to
track.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
1...INT_MAX
Initial Value:
100
Default Value:
100
Example:
/*/mta/rcptMaxHarvesters: [100]
UFSW3RWHQWLDO+DUYHVWHU77/0LQXWHV
154
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
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
1...INT_MAX
Initial Value:
3
Default Value:
3
Example:
/*/mta/rcptPotentialHarvesterTTLMinutes: [3]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHMHFW'QV6HUYH
Description:
Specially configured DNS server to use when looking for domains
to reject.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid host name
Initial Value:
null
Default Value:
null
Example:
/*/mta/rejectDnsServer: [pluto]
UHMHFW,QYDOLG)URP$GGU
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rejectInvalidFromAddr: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
155
InterMail Kx Reference Guide
UHMHFW6HQGHU%DG$GGUHVV
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]
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
false or true
Initial Value:
false
Default Value:
false
Example:
/*/mta/rejectSenderBadAddress: [false]
UHMHFW6HQGHU%DG'RPDLQ
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.
156
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rejectSenderBadDomain: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHMHFW6HQGHU,S'RPDLQ
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rejectSenderIpDomain: [false]
UHMHFW6HQGHU1R'RPDLQ
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rejectSenderNoDomain: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
157
InterMail Kx Reference Guide
UHOD\'HVW$OORZ/LVW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a valid domain name
Initial Value:
null
Default Value:
null
Example:
/*/mta/relayDestAllowList:
[accordance.com]
[software.com]
UHOD\'HVW'HQ\/LVW
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.
158
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a valid domain name
Initial Value:
null
Default Value:
null
Example:
/*/mta/relayDestDenyList: [accordance.com]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHOD\+RVW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid host name
Initial Value:
null
Default Value:
null
Example:
/*/mta/relayHost: [jupiter]
UHOD\/RFDO'RPDLQV2N
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/relayLocalDomainsOk: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
159
InterMail Kx Reference Guide
UHOD\/RFDO0XVW([LVW
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.
160
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/relayLocalMustExist: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHOD\0D[5&37V
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
0
Default Value:
0
Example:
/*/mta/relayMaxRCPTs: [0]
Confidential and Proprietary, © Software.com, Inc. 1999
161
InterMail Kx Reference Guide
UHOD\1XOO5HVWULFWHG
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/relayNullRestricted: [true]
UHOD\5HSO\&RGH
162
Description:
Error code to return in response to RCPT TO if the number of
recipients reaches relayMaxRCPT.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
an error code
Initial Value:
550
Default Value:
550
Example:
/*/mta/relayReplyCode: [550]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHOD\5HSO\7H[W
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a text string
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]
UHOD\6RXUFH'RPDLQ/LVW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
163
InterMail Kx Reference Guide
UHOD\6RXUFH/RFDO,S/LVW
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.
164
Related Keys:
relaySourcePolicy
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any valid IP address
Initial Value:
null
Default Value:
null
Example:
/*/mta/relaySourceLocalIpList:
[10.3.21.0]
[10.20.20.0]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHOD\6RXUFH3ROLF\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
allowAll, denyAll, allowListed, denyListed
Initial Value:
allowAll
Default Value:
allowAll
Example:
/*/mta/relaySourcePolicy: [denyAll]
Confidential and Proprietary, © Software.com, Inc. 1999
165
InterMail Kx Reference Guide
UHOD\6RXUFH5HPRWH,S/LVW
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.
Related Keys:
relaySourcePolicy
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
a valid IP address
Initial Value:
null
Default Value:
null
Example:
/*/mta/relaySourceRemoteIpList: [10.20.20.0]
UHSRUW3DUDPV,QWHUYDO
166
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than 1
Initial Value:
180
Default Value:
180
Example:
/*/common/reportParamsInterval: [180]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHTXLUH&U/I
Description:
Servers should terminate lines with CRLF. Setting requireCRLF to
true prevents bare line feed characters from terminating lines.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/requireCrLf: [false]
UHTXLUH6HFXUH$XWK
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/requireSecureAuth: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
167
InterMail Kx Reference Guide
UHZULWH'RPDLQV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rewriteDomains: [true]
UHZULWH*DWHZD\+HDGHU/LVW
168
Description:
List of headers on outgoing mail to rewrite headers.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
the name(s) of any headers that may contain addresses
Initial Value:
null
Default Value:
null
Example:
/*/mta/rewriteGatewayHeaderList: [To:]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHZULWH+HDGHU/LVW
Description:
List of headers on incoming mail to rewrite headers. If a null value
is specified, headers are not rewritten.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
the name(s) of any headers that may contain addresses
Initial Value:
null
Default Value:
null
Example:
/*/mta/rewriteHeaderList:
[To:]
[From:]
UHZULWH0D[0WD+RSV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
1
Default Value:
1
Example:
/*/mta/rewriteMaxMtaHops: [2]
Confidential and Proprietary, © Software.com, Inc. 1999
169
InterMail Kx Reference Guide
UHZULWH2QO\/RFDO
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/rewriteOnlyLocal: [false]
UHZULWH3ULPDU\
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.
170
Related Keys:
rewriteDomains
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/rewritePrimary: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UHZULWH6DYH2ULJ
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
mta/rewriteSaveOrig: [true]
UPH$FFHVV/LVW
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:
Servers Affected:
all servers
Change Impact:
Trivial
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: [ ]
Confidential and Proprietary, © Software.com, Inc. 1999
171
InterMail Kx Reference Guide
UPH&RQQHFW7LPHRXW
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
10
Default Value:
10
Example:
/*/common/rmeConnectTimeout: [10]
UROORYHUV3HU'D\
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.
172
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any integer from 1 to 1440
Initial Value:
1
Default Value:
0
Example:
/*/common/rolloversPerDay: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
UROORYHU7LPH=HUR
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
any integer from 0 to 86399
Initial Value:
0
Default Value:
0
Example:
/*/common/rolloverTimeZero: [18000]
570,DERUW2Q6KDUHG0HPRU\)DLO
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
Servers Affected:
all
Change Impact:
Do not change the value of this key. Changing the value of this key
may cause the servers to fail to operate.
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/RTMIabortOnSharedMemoryFail:[false]
Confidential and Proprietary, © Software.com, Inc. 1999
173
InterMail Kx Reference Guide
570,'LVDEOH
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
Servers Affected:
all
Change Impact:
Do not change the value of this key. Changing the value of this key
may cause the servers to fail to operate.
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/common/RTMIDisable:[true]
Description:
Working directory for the InterMail servers.
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
a valid directory path
Initial Value:
/var/tmp
Default Value:
/tmp
Example:
/*/common/runDir: [/var/tmp]
UXQ'LU
174
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VFDQ2OG0HVVDJHV,QWHUYDO,Q+RXUV
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
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
any non-negative integer representing number of hours
Initial Value:
24
Default Value:
24
Example:
/*/mta/scanOldMessagesIntervalInHours: [24]
VHUYHU/LQH/HQJWK/LPLW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
1000
Default Value:
1000
Example:
/*/mta/serverLineLengthLimit: [1000]
Confidential and Proprietary, © Software.com, Inc. 1999
175
InterMail Kx Reference Guide
VHUYHU7KUHDG6WDFN6L]H,Q.%
Description:
Size (in kilobytes) of the stack used by MSS threads.
Related Keys:
none
Servers Affected:
MSS
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
64
Default Value:
0
Example:
/*/mss/serverThreadStackSizeInKB: [128]
VHUYHU7LPHRXW
176
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
Servers Affected:
Configuration server
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
30
Default Value:
30
Example:
/*/imconferv/serverTimeout: [30]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VHUYHU7RWDO/LQHV/LPLW
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
100
Default Value:
100
Example:
/*/mta/serverTotalLinesLimit: [100]
VHUY:DUQ7R6WGHUU
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/servWarnToStderr: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
177
InterMail Kx Reference Guide
VKDUHG'LU
Description:
This directory is used to build the path to the nlslib directory
during application (server) startup.
Related Keys:
none.
Servers Affected:
all servers
Change Impact:
Server restart required
Possible Values:
A valid absolute path name.
Initial Value:
The install directory specified at installation time.
Default Value:
null
Example:
/*/common/sharedDir: [/imail/imail]
VLGHOLQH0HVVDJHV
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.
178
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/sidelineMessages: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VLGHOLQH1XOO7R0DQ\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/sidelineNullToMany: [true]
VLGHOLQH1XP5FSWV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any non-negative integer (including zero)
Initial Value:
0
Default Value:
0
Example:
/*/mta/sidelineNumRcpts: [1000]
Confidential and Proprietary, © Software.com, Inc. 1999
179
InterMail Kx Reference Guide
VLGHOLQH1XP5FSWV3HU&RQQHFWLRQ
Description:
Maximum number of recipients allowed over a given connection
before sidelining messages.
A value of zero means there is no limit.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
0
Default Value:
0
Example:
/*/mta/sidelineNumRcptsPerConnection: [0]
VPWS$FFHSW1XP7KUHDGV
180
Description:
Maximum number of threads for the MTA’s SMTP server task, the
task responsible for receiving incoming messages.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
an integer from 1 to 1000
Initial Value:
10
Default Value:
10
Example:
/*/mta/smtpAcceptNumThreads: [10]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VPWS'HOLYHU1XP7KUHDGV
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:
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
an integer from 1 to 1000
Initial Value:
10
Default Value:
10
Example:
/*/mta/smtpDeliverNumThreads: [10]
VPWS3RUW
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
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
25
Default Value:
25
Example:
/*/mta/smtpPort: [25]
Confidential and Proprietary, © Software.com, Inc. 1999
181
InterMail Kx Reference Guide
VPWS4XHXH%XFNHW&RXQW
Description:
Number of buckets in the spool/SMTP-Deliver directory. These
buckets store the messages queued for delivery to external sites.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
101
Default Value:
101
Example:
/*/mta/smtpQueueBucketCount: [101]
VPWS4XHXH3URFHVV1XP7KUHDGV
182
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
10
Default Value:
10
Example:
/*/mta/smtpQueueProcessNumThreads: [10]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VQPS5HFRQQHFW1DS7LPH
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
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0)
Initial Value:
15
Default Value:
15
Example:
/*/common/snmpReconnectNapTime: [15]
VVO&DFKH$JH6HFRQGV
Description:
Lifetime (in seconds) of an SSL session cache entry. The system
expires entries older than the number of seconds specified.
Related Keys:
none
Servers Affected:
MTA, POP server, IMAP server
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
7200
Default Value:
7200
Example:
/*/popserv/sslCacheAgeSeconds: [7200]
Confidential and Proprietary, © Software.com, Inc. 1999
183
InterMail Kx Reference Guide
VVO&DFKH%XFNHW/HQ
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
Servers Affected:
MTA, POP server, IMAP server
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
1000
Default Value:
1000
Example:
/*/imapserv/sslCacheBucketLen: [1200]
VVO&DFKH%XFNHW1XP
184
Description:
Number of buckets in the SSL session cache.
Related Keys:
none
Servers Affected:
MTA, POP server, IMAP server
Change Impact:
server restart required
Possible Values:
any integer greater than zero
Initial Value:
499
Default Value:
499
Example:
/*/popserv/sslCacheBucketNum: [499]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VVO&HUW&KDLQ3DWK$QG)LOH
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
Change Impact:
server restart required
Possible Values:
a valid file path
Initial Value:
null
Default Value:
null
Example:
/*/mta/sslCertChainPathAndFile: [<pathname>]
VVO&HUW3DVVZRUG
Description:
Specifies the SSL password.
Related Keys:
none
Servers Affected:
MTA, POP server, IMAP server
Change Impact:
server restart required
Possible Values:
a text string
Initial Value:
InterMail
Default Value:
InterMail
Example:
/*/mta/sslCertPassword: [InterMail]
Confidential and Proprietary, © Software.com, Inc. 1999
185
InterMail Kx Reference Guide
VVO,PDS3RUW
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
Servers Affected:
IMAP server
Change Impact:
server restart required
Possible Values:
integer values
Initial Value:
993
Default Value:
CFG_ABSURD_PORT_NUMBER
Example:
/host/imapserv/sslImap4Port: [993]
VVO3RS3RUW
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.
186
Related Keys:
none
Servers Affected:
POP server
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
443
Default Value:
-1
Example:
/*/popserv/sslPop3Port: [443]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VVO6PWS3RUW
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
Servers Affected:
MTA
Change Impact:
server restart required
Possible Values:
any valid, unused port number
Initial Value:
465
Default Value:
-1
Example:
/*/mta/sslSmtpPort: [465]
VVO7UXVWHG&HUW3DWK$QG)LOH
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
Change Impact:
server restart required
Possible Values:
any valid file path
Initial Value:
null
Default Value:
null
Example:
/*/mta/sslTrustedCertPathAndFile: [imail/imail/
lib/certs/im_default_certs.txt]
Confidential and Proprietary, © Software.com, Inc. 1999
187
InterMail Kx Reference Guide
VVO8VH6HVVLRQ&DFKH
Description:
Indicates whether to use the SSL session cache.
Related Keys:
none
Servers Affected:
MTA, POP server, IMAP server
Change Impact:
server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/popserv/sslUseSessionCache: [true]
VWDW1DPHG3LSH0RGH
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.
188
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
0, 1
Initial Value:
0
Default Value:
0
Example:
/*/common/statNamedPipeMode: [1]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
VWDW5HFRUGHU6L]H
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
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0).
Initial Value:
10240
Default Value:
10240
Example:
/*/common/statRecorderSize: [10240]
VXE'RPDLQV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
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]
Confidential and Proprietary, © Software.com, Inc. 1999
189
InterMail Kx Reference Guide
WLPHRXW&OLHQW'DWD
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer from 300 to 28800
Initial Value:
600 (10 minutes)
Default Value:
300 (5 minutes)
Example:
/*/mta/timeoutClientData: [600]
WLPHRXW&OLHQW'DWD'RW
190
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 600
Initial Value:
600 (10 minutes)
Default Value:
900 (15 minutes)
Example:
/*/mta/timeoutClientDataDot: [900]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
WLPHRXW&OLHQW'DWD6HQG
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when sending message data.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 180
Initial Value:
180
Default Value:
300
Example:
/*/mta/timeoutClientDataSend: [300]
WLPHRXW&OLHQW*UHHW
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when waiting for a response to the SMTP greeting.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 300
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientGreet: [600]
Confidential and Proprietary, © Software.com, Inc. 1999
191
InterMail Kx Reference Guide
WLPHRXW&OLHQW+HOR
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when waiting for a response to the HELO command.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 300
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientHelo: [600]
WLPHRXW&OLHQW0DLO)URP
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.
192
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 300
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientMailFrom: [600]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
WLPHRXW&OLHQW4XLW
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when waiting for a response to the QUIT command.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer from 300 to 28800
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientQuit: [600]
WLPHRXW&OLHQW5FSW7R
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when waiting for a response to the RCPT TO command.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 300
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientRcptTo: [600]
Confidential and Proprietary, © Software.com, Inc. 1999
193
InterMail Kx Reference Guide
WLPHRXW&OLHQW5VHW
Description:
Socket timeout value (in seconds) for the SMTP-Deliver process
when waiting for a response to the RSET command.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than or equal to 300
Initial Value:
300
Default Value:
600
Example:
/*/mta/timeoutClientRset: [600]
WLPHRXW6HUYHU&RPPDQG
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
194
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
300
Default Value:
0
Example:
/*/mta/timeoutServerCommand: [300]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
WLPHRXW6HUYHU'DWD
Description:
Timeout value (in seconds) for reads and writes when responding a
DATA command.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
300
Default Value:
0
Example:
/*/mta/timeoutServerData: [300]
WLPHRXW6HUYHU'HOLYHU\
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
5
Default Value:
5
Example:
/*/mta/timeoutServerDelivery: [5]
Confidential and Proprietary, © Software.com, Inc. 1999
195
InterMail Kx Reference Guide
WLPHRXW6HUYHU'HOLYHU\5HMHFWLRQ
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
Servers Affected:
MTA
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0).
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.
WPS'LU
tmpDir can be an absolute path or a path relative to the InterMail
installation directory.
196
Related Keys:
none
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
a valid directory path
Initial Value:
tmp
Default Value:
tmp
Example:
/*/common/tmpDir: [tmp]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
WUDFH1DPHG3LSH0RGH
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
Servers Affected:
all servers
Change Impact:
server restart required
Possible Values:
0, 1, or 2
Initial Value:
0
Default Value:
0
Example:
/*/common/traceNamedPipeMode: [1]
WUDFH2XWSXW/HYHO
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
any valid trace category/number
Initial Value:
null
Default Value:
null
Example:
/paris/mta/traceOutputLevel: [rme=1,sock=2]
Confidential and Proprietary, © Software.com, Inc. 1999
197
InterMail Kx Reference Guide
WUDFH5HFRUGHU6L]H
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.
Change Impact:
Trivial
Possible Values:
Any non-negative integer (including 0)
Initial Value:
10240
Default Value:
10240
Example:
/*/common/traceRecorderSize: [10240]
WUDFH7R6WGHUU
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.
198
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/traceToStderr: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
WUDFN5FSW+DUYHVWHUV
Description:
Indicates whether to track and block RCPT TO: harvesters.
Related Keys:
Has no effect if /*/mta/verifyRCPTs is false.
Servers Affected:
MTA
Change Impact:
trivial
Possible Values:
false or true
Initial Value:
false
Default Value:
false
Example:
/*/mta/trackRcptHarvesters: [false]
WUDS0DVN
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
Servers Affected:
SNMP server
Change Impact:
trivial, no server restart required
Possible Values:
notification, warning, error, urgent, fatal
Initial Value:
fatal and urgent
Default Value:
null
Example:
/*/common/trapMask:
[fatal]
[urgent]
Confidential and Proprietary, © Software.com, Inc. 1999
199
InterMail Kx Reference Guide
WUDS4XHXH6L]H
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
Servers Affected:
SNMP server
Change Impact:
server restart required
Possible Values:
any integer from 512 to 4096
Initial Value:
1024
Default Value:
1024
Example:
/*/common/trapQueueSize: [1024]
XSGDWH6HUYHU'1
200
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
Servers Affected:
all servers
Change Impact:
Warning! Do not attempt to modify the value of this key.
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]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
XVH%RXQG7KUHDGV
Description:
Determines whether or not to use bound threads.
Related Keys:
none
Servers Affected:
All servers potentially
Change Impact:
Server restart required
Possible Values:
true, false
Initial Value:
false
Default Value:
/*/common/useBoundThreads: [false]
/*/mss/useBoundThreads: [true]
/*/imapserv/useBoundThreads: [true]
Example:
/*/common/useBoundThreads: [false]
XVH&RQWHQW'LVSRVLWLRQ
Description:
A setting of true allows the writing of the ContentDisposition 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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
null
Default Value:
false
Example:
/*/common/useContentDisposition: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
201
InterMail Kx Reference Guide
XVH0PDS5HDGV
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
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/useMmapReads: [false]
XVH0PDS:ULWHV
202
Description:
Indicates whether to use memory mapped writes. If true, then the
system uses memory mapping to write files.
Related Keys:
none
Servers Affected:
all servers
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/common/useMmapWrites: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
XVH0[
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/mta/UseMx: [true]
YDOLGDWRU%DWFK6L]H
Description:
Maximum number of directory lookups to perform concurrently.
Related Keys:
none
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
any integer greater than zero
Initial Value:
5
Default Value:
1
Example:
/*/mta/validatorBatchSize: [5]
Confidential and Proprietary, © Software.com, Inc. 1999
203
InterMail Kx Reference Guide
YHULI\'HIHU2N
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
204
Related Keys:
blockLocalNoAcct
blockPerAccount
relayLocalMustExist
verifyRCPTs
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/verifyDeferOk: [false]
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys
YHULI\5FSWV
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
Servers Affected:
MTA
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
false
Default Value:
false
Example:
/*/mta/verifyRcpts: [false]
YHUVLRQ&RQILJ'%
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
Servers Affected:
Configuration server
Change Impact:
trivial, no server restart required
Possible Values:
true or false
Initial Value:
true
Default Value:
true
Example:
/*/imconfserv/versionConfigDB: [true]
Confidential and Proprietary, © Software.com, Inc. 1999
205
InterMail Kx Reference Guide
ZHOFRPH0VJ,G
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>.
206
Related Keys:
none
Servers Affected:
MSS
Change Impact:
trivial, no server restart required
Possible Values:
any valid RFC822 message ID.
Initial Value:
<Welcome>
Default Value:
null
Example:
/*/mss/WelcomeMsgId: [<Welcome>]
Confidential and Proprietary, © Software.com, Inc. 1999
3
Directory 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
imdbcontrol
The 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.
Confidential and Proprietary, © Software.com, Inc. 1999
207
InterMail Kx Reference Guide
imdbcontrol Syntax
The syntax for using imdbcontrol is :
imdbcontrol [-help] [-d] [-e] [-q] [-v][-p <N>] [-] [-h]
<option>...
Where:
-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).
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 ...
208
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
In addition, you can abbreviate imdbcontrol command line options. For example,
you can enter:
imdbcontrol CreateAccount
as:
imdbcontrol ca
Available imdbcontrol Operations
The following tables provide information on the execution options available with
imdbcontrol.
Domain 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.
Account Operations
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.
Confidential and Proprietary, © Software.com, Inc. 1999
209
InterMail Kx Reference Guide
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.
Mail Delivery Operations
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.
SMTP Alias Operations
210
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Class-of-Service Operations
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 Operations
This 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:
<domain>
Name of the new domain.
<relayHost>
Host to which the system routes mail received for the nonauthoritative domain. Only necessary if the new domain is a
non-authoritative domain.
Confidential and Proprietary, © Software.com, Inc. 1999
211
InterMail Kx Reference Guide
<rewriteValue>
Domain name that replaces the domain value when rewriting
header addresses. Only necessary if the new domain is a
rewrite 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.
'HOHWH'RPDLQGG
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:
212
<domain>
Name of the domain to delete.
force
Removes the domain from the Integrated Services Directory
permanently.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
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.
*HW'HIDXOW'RPDLQJGG
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.
/LVW'RPDLQVOG
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:
Type:
RelayHost:
RewriteDomain:
WildcardAcct:
--Domain:
Type:
RelayHost:
RewriteDomain:
WildcardAcct:
--^^^ # Domains =
software.com
L
unknown@software.com
venus.software.com
R
software.com
2
Confidential and Proprietary, © Software.com, Inc. 1999
213
InterMail Kx Reference Guide
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 (nonauthoritative), 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.
6HW:LOGFDUG$FFRXQWVZ
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 email sent to unknown addresses within the domain.
For example, if the account john.doe@software.com 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 john.doe@software.com.
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:
<domain>
Name of the domain.
<username>
Address of the e-mail account that will be a wildcard
account for this domain.
Example
imdbcontrol sw mars.software.com unknown
This command sets the e-mail account unknown@mars.software.com as the
wildcard account for the domain mars.software.com.
214
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
8QVHW:LOGFDUG$FFRXQWXZ
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:
<domain>
Name of the domain to remove wildcard delivery from.
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.
8SGDWH'RPDLQXG
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 existing domain.
<relayHost>
Host to which the system routes mail received for the nonauthoritative 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.
Confidential and Proprietary, © Software.com, Inc. 1999
215
InterMail Kx Reference Guide
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 Operations
The imdbcontrol operations described in this section are specific to InterMail
account-related mail objects.
&UHDWH$FFRXQWFD
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:
216
<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>
-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 to associate the account with. If you do not
specify a domain, it assumes the default domain.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
<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.
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 john.doe@software.com).
•
•
•
•
•
•
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.
'HOHWH$FFRXQWGD
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
Example
imdbcontrol da john.doe software.com
This example deletes the account that has the e-mail address
john.doe@software.com.
Confidential and Proprietary, © Software.com, Inc. 1999
217
InterMail Kx Reference Guide
'HOHWH$FFRXQW&RVGDF
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
<attribute>
Name of the attribute to delete from the account.
Example
imdbcontrol dac jdoe software.com pref_imap
This example deletes the class of service attribute pref_imap from the account
jdoe@software.com.
*HW$FFRXQWJD
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:
218
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Example
imdbcontrol ga john.doe software.com
This example retrieves all of the mail account information for the account
john.doe@software.com. The output from this command looks like:
Account Info:
--Type:
Status:
Internal-ID:
Delivery Host:
Domain Name:
PSMTP Address:
POP Address:
Password:
Password Hash:
Forward:
LocalDelivery:
AutoReply Host:
AutoReply Mode:
COS Name:
---
S
A
10671
pluto.software.com
software.com
john.doe
jdoe
rosebud
C
N
P
pluto.software.com
N
default
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).
Confidential and Proprietary, © Software.com, Inc. 1999
219
InterMail Kx Reference Guide
*HW$FFRXQW&RVJDF
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
Example
imdbcontrol gac jdoe software.com
This example retrieves class of service attribute values for the account
jdoe@software.com. 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
220
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Attribute Name
Syntax
Rule
COS
Value
Account
Value
Result
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
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.
Confidential and Proprietary, © Software.com, Inc. 1999
221
InterMail Kx Reference Guide
*HW3DVVZRUGJS
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
Example
imdbcontrol gp john.doe software.com
This command gets the password for the account john.doe@software.com.
/LVW$FFRXQWVOD
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:
<domain>
Domain to query for account information. If you do not
specify a domain, it retrieves information for all domains.
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.
222
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
The format of the information that ListAccounts displays for each account as
follows:
Addr:
Pass:
Pass-Type:
Type:
Status:
Host:
IntID:
Local Delivery:
ForwardFlag:
AutoReplyMode:
AutoReplyHost:
john.doe@software.com
rosebud
C
S
A
venus
6
P
N
N
pluto
The above data includes the following information for an account:
•
•
•
Primary e-mail address (Addr).
•
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).
Login password (Pass).
Password hashing scheme (Pass-Type). The value of this field can be C (clear),
U (UNIX), or M (MD5).
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.
0RGLI\$FFRXQWPD
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.
Confidential and Proprietary, © Software.com, Inc. 1999
223
InterMail Kx Reference Guide
Usage
imdbcontrol ma <username> <mssHost> <internalId> <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 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.
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.
224
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
0RGLI\$FFRXQW3RSPDS
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
<popLogin>
New POP/IMAP login name value.
Example
imdbcontrol map john.doe software.com johndoe
This example changes the POP/IMAP login name of the account
john.doe@software.com to johndoe.
0RGLI\$FFRXQW6PWSPDV
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
<newUsername>
New username value for the account.
<newDomain>
New domain for the account.
Confidential and Proprietary, © Software.com, Inc. 1999
225
InterMail Kx Reference Guide
Example
imdbcontrol mas john.doe software.com jdoe sales.software.com
This example changes the primary e-mail address of an account from
john.doe@software.com to jdoe@sales.software.com.
6HW$FFRXQW&RVVDF
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
<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.
Example
imdbcontrol sac jdoe software.com pref_imap 1
This example sets values for the class of service attribute pref_imap for the account
jdoe@software.com. The value 1 indicates that the command is setting this
Boolean attribute to true.
226
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
6HW$FFRXQW4XRWDVDT
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with 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).
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
john.doe@software.com. 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.
Confidential and Proprietary, © Software.com, Inc. 1999
227
InterMail Kx Reference Guide
6HW$FFRXQW6WDWXVVDV
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
<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).
Example
imdbcontrol sas john.doe software.com S
This example changes the status of the account john.doe@software.com to
suspended (S).
6HW$XWR5HSO\VDU
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:
228
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
<autoReplyMode>
Mode of auto-reply the account uses. The possible values for
this parameter are N (none), V (vacation), R (reply), E (echo).
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Example
imdbcontrol sar john.doe software.com V
This example enables an auto-reply for the account john.doe@software.com,
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 autoreply 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.
6HW$XWR5HSO\+RVWVDUK
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 autoreply 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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
<autoReplyHost>
Host name of the system storing the account’s auto-reply message.
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 john.doe@software.com.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
229
InterMail Kx Reference Guide
6HW3DVVZRUGVS
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
<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.
Example
imdbcontrol sp john.doe software.com $ecret clear
This example changes the password for the account john.doe@software.com to
$ecret, stored in clear text format.
6HW3UR[\+RVWVVSK
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:
230
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
<popHost>
The POP/IMAP host from which this account will access
mail.
<smtpHost>
The SMTP host where mail for this account will be delivered.
Mail Delivery Operations
&UHDWH5HPRWH)RUZDUGFUI
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<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.
Example
imdbcontrol crf john.doe software.com jdoe@Wossamotta-U.edu
This example creates the forwarding address jdoe@Wossamotta-U.edu for the
account john.doe@software.com.
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.
'HOHWH5HPRWH)RUZDUGGUI
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.
Confidential and Proprietary, © Software.com, Inc. 1999
231
InterMail Kx Reference Guide
Usage
imdbcontrol drf <username> <domain> <forwardTo>
Where:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account’s primary SMTP
address
<forwardTo>
Complete remote forwarding address to delete.
Example
imdbcontrol drf john.doe software.com jdoe@Wossamotta-U.edu
This example deletes the remote forwarding address jdoe@Wossamotta-U.edu that
the CreateRemoteForward example created for the local account
john.doe@software.com.
Note:
Deleting an account’s last forwarding address automatically enables local
(POP) delivery for the account, if previously disabled.
'LVDEOH)RUZDUGLQJGI
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:
232
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account’s primary SMTP address
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Example
imdbcontrol df john.doe software.com
This command disables forwarding delivery for the account
john.doe@software.com. 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.
'LVDEOH323'HOLYHU\GSG
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
Example
imdbcontrol dpd john.doe software.com
This command disables local delivery for the account john.doe@software.com.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
233
InterMail Kx Reference Guide
(QDEOH)RUZDUGLQJHI
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account’s primary SMTP address
Example
imdbcontrol ef john.doe software.com
This command enables forwarding delivery for the account
john.doe@software.com. With this delivery method enabled, the system will
forward all messages sent to john.doe@software.com to the forwarding addresses
defined for this account.
(QDEOH323'HOLYHU\HSG
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:
234
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Example
imdbcontrol epd john.doe software.com
This command enables local delivery for the account john.doe@software.com.
With this delivery method enabled, all messages sent to john.doe@software.com
will go to the account’s mailbox, from which the POP3 Server or IMAP Server can
retrieve them.
/LVW$FFRXQW)RUZDUGVODI
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:
<username>
Local part of the SMTP address for the account (the part that
precedes the “@” symbol in the e-mail address).
<domain>
Domain associated with the account’s primary SMTP address
Example
imdbcontrol laf john.doe software.com
This command lists the local and remote forwarding addresses associated with the
account john.doe@software.com. Output from this command includes only the
relevant forwarding addresses, one per line. For example:
joe.schmoe@accordance.com
jdoe@Wossamotta-U.edu
SMTP Alias Operations
&UHDWH$OLDVFO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
235
InterMail Kx Reference Guide
Usage
imdbcontrol cl <username> <aliasUsername> [<domain>] [<aliasDomain>]
Where:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<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.
Example
imdbcontrol cl john.doe sales software.com software.com
This command adds the alias address sales@software.com to the account whose
primary SMTP address is john.doe@software.com.
'HOHWH$OLDVGO
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:
<username>
Local portion of the alias address to delete.
<domain>
Domain of the alias address.
Example
imdbcontrol dl sales software.com
This command deletes the alias address sales@software.com created in the
CreateAlias example.
236
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
/LVW$OLDVHVOO
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:
<username>
Local part of the SMTP address for the account (the
part that precedes the “@” symbol in the e-mail
address).
<domain>
Domain associated with the account’s primary SMTP
address.
Example
imdbcontrol ll john.doe software.com
This command returns a list of SMTP aliases associated with the account
john.doe@software.com.
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 Operations
The imdbcontrol operations described in this section relate to InterMail classes of
service.
&UHDWH&RVFF
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.
Confidential and Proprietary, © Software.com, Inc. 1999
237
InterMail Kx Reference Guide
Usage
imdbcontrol cc <classOfService>
Where:
<classOfService>
Name of the new class of service.
Example
imdbcontrol cc Premium
This example creates a new class of service named “Premium”.
&UHDWH&RV$WWULEXWHFFD
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:
<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).
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.
238
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
'HOHWH&RVGF
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:
Name of the class of service to delete.
<classOfService>
Example
imdbcontrol dc Premium++
This command deletes the class of service named “Premium++”.
'HOHWH&RV$WWULEXWHGFD
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:
<attribute>
Name of the class of service attribute to delete.
Example
imdbcontrol dca pref_pager
This example deletes the class of service attribute named pref_pager.
/LVW&RV$WWULEXWHVOFD
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)
Confidential and Proprietary, © Software.com, Inc. 1999
239
InterMail Kx Reference Guide
•
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:
Name:
Name:
Name:
...
pref_quotatotmsgs; Rule: A; Syntax: N
perm_vacation; Rule: L; Syntax: N
pref_intermanager; Rule: A; Syntax: B
pref_quotamsgkb; Rule: A; Syntax: N
/LVW&RV1DPHVOFQ
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
0RGLI\&RV$WWULEXWHPFD
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.
240
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
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.
6HW&RV$WWULEXWHVFD
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:
<classOfService>
Name of the class of service for which to define the
attribute.
<attribute>
Name of the attribute.
<value>
Value of the attribute.
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.
6KRZ&RVVF
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:
<classOfService>
Name of the class of service to query.
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:1
pref_smtpssl:1
Confidential and Proprietary, © Software.com, Inc. 1999
241
InterMail Kx Reference Guide
8QVHW&RV$WWULEXWHXFD
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:
<classOfService>
Name of the class of service for which to remove the
attribute.
<attribute>
Name of the attribute.
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.
imbatchextract
The 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 Syntax
The 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:
242
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
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:
-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.
Note:
The arguments –d, -p, -s and –t are allowed only when the object type is
account.
Confidential and Proprietary, © Software.com, Inc. 1999
243
InterMail Kx Reference Guide
Creating a Targeted User Batch File
Using 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 Syntax
The syntax for using imbatchload is:
imbatchload [options] <files- | ->
Where:
[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.
When executed, imbatchload takes the contents of the specified input file(s) and
imports the data into the InterManager data hierarchy.
244
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
The options for imbatchload are:
-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
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:
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)
Confidential and Proprietary, © Software.com, Inc. 1999
245
InterMail Kx Reference Guide
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.
246
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Summary of Record Sequencing
To summarize, the overall structure for the batch loading input file is as follows:
Context
Domain (optional unless Organization is being created)
Organization
organization attributes
OrgUnit
<organizational unit attributes>
[optionally repeat OrgUnit to get child organizational units]
Person
<person attributes>
Input File Record Types
The 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.
Confidential and Proprietary, © Software.com, Inc. 1999
247
InterMail Kx Reference Guide
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 optional
messageStoreHost: <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
248
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
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: SiteAdmin
maxusers: 10
messagestorehost: 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
Confidential and Proprietary, © Software.com, Inc. 1999
249
InterMail Kx Reference Guide
Option
Description
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
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: Person
mailCOS: MegaBasic
passwordType: MD5
mailboxStatus: locked
Change Records
The ChangeType record alters the processing of entry records. Available change
types are:
Type
add
250
Description
Add the record (the default)
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
Type
Description
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.
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: Person
uid: john.doe@software.com
add: postalCode
postalCode: 98004
modify: billingId
billingId: 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.
imintegcheck
The 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.
Confidential and Proprietary, © Software.com, Inc. 1999
251
InterMail Kx Reference Guide
imintegcheck Syntax
imintegcheck [-help] [-h <host>] [-p <port>] [-b <search Base>]
[<option>]
Where:
-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.
Note:
All operations can specified with abbreviations using the first initials of the
words in the argument (for example, ‘lea' for ListExtraAccounts).
imintegcheck Operations
The 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.
252
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
•
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’
ldapadd
The 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]
Confidential and Proprietary, © Software.com, Inc. 1999
253
InterMail Kx Reference Guide
ldapdelete
The 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:
-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.
See http://www.rfc-editor.org/rfcsearch.html
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.
254
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
ldapmodify
The 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.
-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.
-d level
Sets the LDAP debugging level to level.
-D binddn
Uses binddn to bind to the X.500 directory. binddn should be a stringrepresented DN as defined in RFC 1779.
-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.
-f file
Reads the entry modification information from file instead of from
standard input.
Confidential and Proprietary, © Software.com, Inc. 1999
255
InterMail Kx Reference Guide
ldapmodrdn
The 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.
-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 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.
-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 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.
See http://www.rfc-editor.org/rfcsearch.html
256
Confidential and Proprietary, © Software.com, Inc. 1999
Directory Management Utilities
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.
ldapsearch
The 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.
-v
Uses verbose mode, with many diagnostics written to standard 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.
Confidential and Proprietary, © Software.com, Inc. 1999
257
InterMail Kx Reference Guide
-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.
-D binddn
Uses binddn to bind to the X.500 directory. binddn should be a stringrepresented 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.
-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.
258
Confidential and Proprietary, © Software.com, Inc. 1999
4
General 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 Descriptions
This 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
Confidential and Proprietary, © Software.com, Inc. 1999
259
InterMail Kx Reference Guide
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.
LPEDGPVJIL[
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:
-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.
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:
paris% imbadmsgfix -v bad
imbadmsgfix:
2.....................................................................
...............
............. 0 messages still in .ERROR
260
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
LPEDWFKH[WUDFW
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.
LPEDWFKORDG
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.
LPER[FUHDWH
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:
-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.
Example
To use imboxcreate to create a message store, run imboxcreate as in the
following example:
paris% imboxcreate paris 123456 1000000
imboxcreate:
Message store 123456 created!
Confidential and Proprietary, © Software.com, Inc. 1999
261
InterMail Kx Reference Guide
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.”
LPER[GHOHWH
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:
-v
Verbose operation.
[-a <file>]
An input file containing e-mail addresses.
[-m <file>]
An input file containing Message Store IDs.
<host>
Host upon which the message store resides.
<InternalID>
Message Store ID.
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:
paris% imboxdelete paris 654321
imboxdelete:
Message store 654321 deleted!
LPER[JHW
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>
262
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Where:
<e-mailAddress>
Valid e-mail address.
Example
To find out the host and Message Store ID for a particular user, run imboxget as in
the following example:
paris% imboxget joe.schmoe@paris.software.com
Host=earth Message store=1000
LPER[VWDWV
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:
-v
Verbose execution.
<MessageStoreName>
Name of a Message Store.
<e-mailAddress>
A valid e-mail address.
Example
paris% imboxstats broc.lee@minorcorp.com
statistics for broc.lee@minorcorp.com are totalMsgs=112/MsgsQuota=0,
totalBytes=2613599/BytesQuota=0
paris%
In this example, Broc’s message store has 112 messages totaling 2613599 kb. There
are no quotas set on this message store.
LPER[WHVW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
263
InterMail Kx Reference Guide
Syntax
imboxtest <host> <LoginName> <Password>
Where:
<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.
Example
To test a user’s ability to connect to a message store from a POP session, run
imboxtest as in the following example:
paris% imboxtest paris john.doe $ecret
+OK
+OK
+OK
+OK
+OK
InterMail POP3 server ready
please send PASS command
john.doe is welcome here
152 1928370
john.doe Intermail POP3 server signing off.
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.
LPEXFNHWVFUHDWH
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.
264
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Syntax
imbucketscreate [<dir> <c1...cn>]
Where:
<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>.
Example
To expand the Messsage File system to include an additional subdirectory, enter the
following:
paris% cd msgfiles
paris% ls
messages
buckets
buckets.dir
paris% mkdir messages_2
paris% pwd
/vol1/imail/msgfiles
paris% ../lib/imbucketscreate messages_2 10 10
imbucketscreate: creating 100 directories under msgfiles_2.
imbucketscreate: finished creating 100 directories under msgfiles_2.
paris% ls
messages
messages_2
buckets
buckets.dir
paris% more buckets.dir
messages
messages_2
paris% ../lib/imbucketscreate
LPFPGOLVW
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:
paris% imcmdlist
Command Name
____________
Description
___________
imbadmsgfix
imbadmsglist
imboxcreate
imboxdelete
............
Moves messages from .ERROR folder to inbox
Lists to file those messages in the .ERROR folder
Creates mailboxes
Deletes mailboxes
Confidential and Proprietary, © Software.com, Inc. 1999
265
InterMail Kx Reference Guide
LPFRQIFRQWURO
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.
LPFRQIHGLW
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:
266
-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.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Example
To modify the configuration database, run imconfedit as in the following example:
paris% imconfedit
imconfserv 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.
/*/common/abortIfLogFails: [false]
/*/common/badPasswordDelay: [5]
/*/common/badPasswordWindow: [120]
/*/common/cacheLimitInKB: [256]
......
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:
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 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>.
Confidential and Proprietary, © Software.com, Inc. 1999
267
InterMail Kx Reference Guide
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:
“
*
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] ?
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.
---- The changes have been made on the config server ---Do you want to re-start the servers now? (Y/N) y
executing “imctrl paris restart imapserv:imconfserv:mss.1:mta:popserv”
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).
268
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
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 hostspecific configuration keys on paris as in the following example:
/*/common/abortIfLogFails: [false]
/earth/common/abortIfLogFails: [true]
......
/*/common/clientHeaps: [16]
/earth/common/clientHeaps: [13]
Configuration management contains much more information than is shown in the
imconfedit or related commands.
LPFRQIJHW
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>] -servers
imconfget -hosts
imconfget -server <name>
where:
-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”.
Confidential and Proprietary, © Software.com, Inc. 1999
269
InterMail Kx Reference Guide
-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>).
Example
To get the value of a single configuration key, run imconfget as in the following
example:
paris% imconfget -h paris -m common binDir
bin
LPFRQI[ODWH
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.
270
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
LPFWUO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
271
InterMail Kx Reference Guide
Example
To control the behavior of servers in the InterMail system remotely, run imctrl as in
the following example:
venus% imctrl localhost restart mta
To execute multiple sets of arguments, run imctrl as in the following example:
venus% imctrl earth restart mta:mss venus start mta venus kill popserv
LPGEFRQWURO
The imdbcontrol command allows you to modify the contents of the database. For
information on imdbcontrol, see Chapter 4.
LPGEPDNH
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.
LPGLUPDNH
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.
LPGEUHFRYHU
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:
272
-h
Produce usage information.
-m
Restore Message Store database and message file system information.
-d
Restore Directory database information.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
LPILOWHUFKHFN
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:
-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.
Note:
See the InterMail Kx Operations Guide for examples of how to use
imfiltercheck.
LPIROGHUOLVW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
273
InterMail Kx Reference Guide
Syntax:
iminboxlist {<MessageStoreName> | <e-mailAddress>} [-folder
<folderName>] [-s][-d][-all | <attribute>]
where:
<MessageStoreName>
Name of a Message Store.
<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.
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.
LPLQER[OLVW
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:
274
<host>
Host upon which the message store resides.
<MessageStoreName>
Name of a Message Store.
<e-mailAddress>
Valid e-mail address.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
-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.
Example
To report header information, run iminboxlist as in the following example:
paris% iminboxlist paris susie.queue@paris.software.com From Subject
0: From: john.doe@paris.Software.com (John Doe)
0: Subject: What’s going on, Susie?
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.
LPORJSULQW
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:
-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.
Confidential and Proprietary, © Software.com, Inc. 1999
275
InterMail Kx Reference Guide
-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.
Example
To format log output from standard input with sample arguments, run imlogprint as
in the following example:
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
To format log output from standard input and place entries on multiple lines with tags,
run imlogprint as in the following example:
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
Finally, to format log output and exclude certain fields from summarization, run
imlogprint as in the following example:
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
276
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
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:
paris% imlogprint -t -m < mta.log
If you choose this option, you will probably want to redirect this output to a second
file (namely, mta.log.printout).
LPORJVXP
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:
-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.
Confidential and Proprietary, © Software.com, Inc. 1999
277
InterMail Kx Reference Guide
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:
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
********************************************************************
LPPVJGHOHWH
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:
278
<host>
Host upon which the message store resides.
<MessageStoreName>
Name of a Message Store.
<e-mailAddress>
Valid e-mail address.
<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.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Example
To delete a message from a user’s message store, run immsgdelete as in the
following example:
paris% immsgdelete paris joe.schmoe@paris.software.com
’<3.0.32.19971112154439.009bc2e0@getmail-earth.software.com>’
Deleting msg 3 -- <3.0.32.19971112154439.009bc2e0@getmailearth.software.com>
Note:
Use iminboxlist to determine Message IDs.
LPPVJGXPS
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:
<host>
Host upon which the message store resides.
<MessageStoreName>
Name of a Message Store.
<e-mailAddress>
Valid e-mail address.
<msgNum>
Number of the message to view (as identified by
imfolderlist or iminboxlist).
Confidential and Proprietary, © Software.com, Inc. 1999
279
InterMail Kx Reference Guide
Example
To show an actual message from a message store, run immsgdump as in the following
example:
paris% immsgdump paris joe.schmoe@paris.software.com 1
Received: from earth.software.com ([1.2.2) by paris.software.com
(InterMail v3.1 117) with ESMTP
id <19971024031526.ABS19760@paris.software.com>
for <joe.schmoe@paris.software.com>;
Thu, 23 Oct 1997 20:15:26 -0700
Date: Thu, 23 Oct 1997 23:16:57 -0400 (EDT)
From: john.doe@paris.Software.com
Message-ID: <971023231330_863569333@emout12.mail.aol.com>
To: joe.schmoe@software.com
Subject: Have you seem Susie?
Have you seen Susie Queue? She was waiting at the printer, but after
the job printed, she went away.
-john
LPPVJILQG
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:
280
<host>
Host upon which the message store resides.
<MessageStoreName>
Name of a Message Store.
<e-mailAddress>
Valid e-mail address.
<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.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Example
To find out a message number, run immsgfind as in the following example:
paris% immsgfind paris joe.schmoe@paris.software.com \
’<3.0.32.19971112160632.009bf240@getmail-earth.software.com>’
3 : Message-ID: <3.0.32.19971112160632.009bf240@getmailearth.software.com>
LPPVJPDVVPDLO
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:
-f <e-mailAddress>
Sender’s e-mail address.
<recipientsFile>
List of e-mail addresses.
<messageFile>
E-mail message to send.
-
Invokes standard input mode.
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:
From: support@yourdomain.net
To: Our Valued Users
Subject: Routine Maintenance
All mail services will be unavailable from 3:00am to 3:30am
tonight while we upgrade our services. We appreciate your
patience while we improve our system to serve you better.
Regards,
Your Systems Administrators
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
Confidential and Proprietary, © Software.com, Inc. 1999
281
InterMail Kx Reference Guide
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:
paris% immsgmassmail to.list From: joe.schmoe@paris.software.com
To: john.doe, susie.queue
Subject: Do not interfere...
Are you guys coming to lunch?
^D
immsgmassmail: Notice: saved message in "/vol1/imail/tmp/
immsgmassmail.980519210155.9522"
joe.schmoe@paris.software.com
susie.queue@paris.software.com
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
LPPVJSURFHVV
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.
282
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Syntax
immsgprocess <controlFile> [<headerFile> [<bodyFile>]]
Where:
<controlFile>
Control file to specify for reprocessing.
<headerFile>
Header file to specify for reprocessing.
<bodyFile>
Body file to specify for reprocessing.
LPPVJYHULI\
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:
paris% immsgverify
find: path-list predicate-list
immsgverify: widows found, see /vol1/imail/tmp/
immsgverify.22184.widows
Confidential and Proprietary, © Software.com, Inc. 1999
283
InterMail Kx Reference Guide
LPPVLQLW
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:
-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.
Examples
To create an administrative message store with a welcome message, run immsinit as
in the following example:
paris% immsinit
immsinit:
immsinit:
immsinit:
immsinit:
connecting to MSS on paris
Creating mailbox for admin
importing a message for admin
Finished building message store for admin
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:
From: Admin
To: New Users
Message-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!
284
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
LPPVVFDOO
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.
LPPWDFKHFN
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:
-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.
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:
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
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.
Confidential and Proprietary, © Software.com, Inc. 1999
285
InterMail Kx Reference Guide
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.
LPRUSKDQUP
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
-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.
LPSRSXVHUVWDWV
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.
286
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Syntax
impopuserstats <LoginName> [<logFile>...[<logFile>]]
Where
<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.*).
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.
paris% impopuserstats testuser1
2
1
1
1
4
970102
970102
970102
970203
970108
13
15
16
14
11
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.
LPSZGKDVK
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).
Confidential and Proprietary, © Software.com, Inc. 1999
287
InterMail Kx Reference Guide
Syntax
impwdhash -a [md5-po|unix] <Password> [<hashedPassword>]
Where:
-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.
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.
paris% impwdhash -a unix $ecret
f3HiwyRyBcEX2paris% imdbcontrol createaccount john.doe
paris@software.com 25 jdoe f3HiwyRyBcEX2 unix
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.
LPTXHXHVSOLW
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
288
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
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:
<destdomain>
Domain name for outgoing queued mail.
<newdest>
Additional domain name(s) for outgoing queued mail.
LPUHSO\FWUO
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:
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.
Confidential and Proprietary, © Software.com, Inc. 1999
289
InterMail Kx Reference Guide
LPVHUYFWUO
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:
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.
Note:
290
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.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
Example
To stop all servers on the local InterMail host, run imservctrl (from the
$INTERMAIL/lib directory) as in the following example:
paris% imservctrl stop
sbs-qasun3% imservctrl stop
imservctrl: Warning: no httpd process found
imservctrl: 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
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:
paris% imservctrl start popserv
LPVHUYGLVSOD\
The imservdisplay command displays information about InterMail servers. This
command displays information from the time of the last server restart.
Syntax
imservdisplay
Confidential and Proprietary, © Software.com, Inc. 1999
291
InterMail Kx Reference Guide
Example
To view a report on server activity, run imservdisplay as in the following example:
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
......
The output from imservdisplay tells the user that servers are in operation and
reports summarized information from log files.
LPVHUYSLQJ
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:
292
-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.
Confidential and Proprietary, © Software.com, Inc. 1999
General Administration Utilities
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:
paris% imservping 1 5
Tue May
Tue May
Tue May
Tue May
......
19
19
19
19
16:08:54
16:08:54
16:08:54
16:08:54
1998.
1998.
1998.
1998.
imservping:
imservping:
imservping:
imservping:
(Info)
(Info)
(Info)
(Info)
mss/mss.1 responded
imconfserv responded
immgrserv responded
imdirserv responded
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.
LPVHUYVKXWGRZQ
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.
LPVPWSFKHFN
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
Confidential and Proprietary, © Software.com, Inc. 1999
293
InterMail Kx Reference Guide
LPVSRROOLVWROGILOHV
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:
-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.
LPV\VPRQ
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:
-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.
Note:
294
For an example of how to configure and run imsysmon, please refer to the
InterMail Kx Operations Guide.
Confidential and Proprietary, © Software.com, Inc. 1999
5
InterMail 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
Introduction
Data 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 Conventions
Types, 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.
Confidential and Proprietary, © Software.com, Inc. 1999
295
InterMail Kx Reference Guide
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 Semantics
Most 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 Conventions
With 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 Initialization
int 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.
296
Confidential and Proprietary, © Software.com, Inc. 1999
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 Types
Every InterMail object’s structure begins with a header that allows the API to do runtime 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).
Confidential and Proprietary, © Software.com, Inc. 1999
297
InterMail Kx Reference Guide
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 Types
The types of objects supported by the InterMail API are:
IM_Error
An error returned by an API function
IM_StringArray
A collection of NULL-terminated strings
The IM_Error and IM_StringArray types are general-purpose utility types.
IM_Domain
An e-mail domain; for example, my.company.com
IM_Account
An account with associated attributes and a mailbox
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).
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
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 email messages.
IM_Reply
An auto-reply message for an account
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.
298
IM_Cos
Class of service definition
IM_CosAttrDef
Attribute referred to by one or more IM_Cos objects
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
IM_CosAttrDefArray
Collection of IM_CosAttrDef objects
The IM_Cos types are associated with the Integrated Services Directory. These
objects control the features of InterMail that are enabled for an account.
IM_Config
Structure to hold configuration data from the
configuration database.
The IM_Config type stores information managed by the InterMail Configuration
Server .
IM_LogContext
Context
used when generating log messages
IM_LogMsg
A log file entry
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,
Confidential and Proprietary, © Software.com, Inc. 1999
299
InterMail Kx Reference Guide
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.
300
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
String Arrays
Interface: 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);
Domains
Interface: 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.
Confidential and Proprietary, © Software.com, Inc. 1999
301
InterMail Kx Reference Guide
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.
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
int
int
int
int
int
max,
IM_ReadDomain (IM_Domain* domain, IM_Error* error);
IM_CreateDomain(IM_Domain* domain, IM_Error* error);
IM_DeleteDomain(IM_Domain* domain, IM_Error* error);
IM_UpdateDomain(IM_Domain* domain, IM_Error* error);
IM_ReadDomains(char* from, char* till, int max,
IM_StringArray* domains, IM_Error* error);
IM_ReadSubDomains(char* topDomain, char* from, char* till, int
IM_StringArray* domains, IM_Error* error);
,0B5HDG'RPDLQ
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.
,0B&UHDWH'RPDLQ
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,
302
Confidential and Proprietary, © Software.com, Inc. 1999
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.
,0B'HOHWH'RPDLQ
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.
,0B8SGDWH'RPDLQ
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
Confidential and Proprietary, © Software.com, Inc. 1999
303
InterMail Kx Reference Guide
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 visaversa) 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.
,0B5HDG'RPDLQV
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.
,0B5HDG6XE'RPDLQV
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
304
Confidential and Proprietary, © Software.com, Inc. 1999
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 deallocated and re-initialized each time IM_ReadSubDomains() is called.
Accounts
Interface: 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,
Confidential and Proprietary, © Software.com, Inc. 1999
305
InterMail Kx Reference Guide
IM_FORWARDING_ENABLED,
IM_FORWARDING_DISABLED
} IM_ForwardFlag;
/* forwarding is enabled. */
/* forwarding is disabled. */
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 :
306
_header
Internal use.
_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.
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
307
InterMail Kx Reference Guide
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*);
,0B&UHDWH$FFRXQW
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:
308
smtpAddress
Required
mssHost
Required (if account status is not IM_ACSTATUS_PROXY)
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
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().
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.
Confidential and Proprietary, © Software.com, Inc. 1999
309
InterMail Kx Reference Guide
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().
,0B8SGDWH$FFRXQW
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.
,0B+DVK3DVVZRUG
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
310
Confidential and Proprietary, © Software.com, Inc. 1999
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.
,0B&KHFN3DVVZRUG
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.
,0B5HVHW$F&RV
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.
,0B8SGDWH$F&RV
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.
To commit these changes to the ISD, call the IM_UpdateAccount function
subsequently.
Confidential and Proprietary, © Software.com, Inc. 1999
311
InterMail Kx Reference Guide
,0B'HOHWH$F&RV
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.
To commit these changes to the ISD, call the IM_UpdateAccount function
subsequently.
,0B8SGDWH$FFRXQW$GGU
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.
,0B'HOHWH$FFRXQW
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.
,0B5HDG$FFRXQW
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
312
Confidential and Proprietary, © Software.com, Inc. 1999
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.
,0B5HDG$OLDV
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().
,0B5HDG323
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().
,0B&UHDWH$OLDV
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.
,0B'HOHWH$OLDV
int IM_DeleteAlias(const char* alias, IM_Error*);
This function deletes an alias identified by the alias argument.
,0B5HDG$FFRXQW$OLDVHV
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.
,0B&UHDWH)RUZDUG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
313
InterMail Kx Reference Guide
,0B'HOHWH)RUZDUG
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.
,0B5HDG$FFRXQW)RUZDUGV
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.
,0B(QDEOH$FFRXQW)RUZDUGV
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.
,0B'LVDEOH$FFRXQW)RUZDUGV
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.
,0B5HDG$FFRXQWV
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,
jill@software.com, jill@west.software.com, and jane@hardware.com,
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
314
Confidential and Proprietary, © Software.com, Inc. 1999
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 deallocated 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 *);
,0B5HDG0ER[
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.
Confidential and Proprietary, © Software.com, Inc. 1999
315
InterMail Kx Reference Guide
,0B&UHDWH0ER[
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 nonNULL 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.
,0B'HOHWH0ER[
int
IM_DeleteMbox(IM_Mbox*, IM_Error*);
Deletes a mailbox.
The caller must set the host and name fields of the IM_Mbox argument.
,0B6HW066&RQQ3RRO6L]H
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.
316
Confidential and Proprietary, © Software.com, Inc. 1999
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_Header
void*
char*
int
int
int
char**
int
int
int*
int*
int*
char**
char**
} IM_Folder;
IM_Folder
_header;
_internalID;
pathname;
numFolders;
readOnly;
clearRecent;
names;
numMsgs;
UIDValidity;
msgRefs;
msgUIDs;
msgSizes;
msgIds;
msgFlags;
The fields of this structure and their syntax are described below:
_header
Internal use.
_internalID
Internal use.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
317
InterMail Kx Reference Guide
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.
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.
318
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
,0B5HDG)ROGHU
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.
,0B&UHDWH)ROGHU
int
IM_CreateFolder(IM_Mbox*, IM_Folder*, IM_Error*);
Create a new folder in a mailbox.
The caller must set the host and name fields of the IM_Mbox argument, and the
pathname field of the IM_Folder argument.
,0B'HOHWH)ROGHU
int
IM_DeleteFolder(IM_Mbox*, IM_Folder*, IM_Error*);
Delete a folder from a mailbox.
The caller must set the host and name fields of the IM_Mbox argument, and the
pathname field of the IM_Folder argument.
,0B5HQDPH)ROGHU
int IM_RenameFolder(IM_Mbox*, IM_Folder*, const char*
dstname,
IM_Error*);
Renames the specified folder.
,0B'HOHWH)ROGHU0VJV
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.
Confidential and Proprietary, © Software.com, Inc. 1999
319
InterMail Kx Reference Guide
,0B6FDQ)ROGHU0VJV
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.
,0B0RYH0VJV
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.
,0B&RS\0VJV
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_Header
void*
int
int
int
char*
time_t
char*
char*
} IM_Msg;
320
IM_Msg
_header;
_internalID;
msgRef;
seen;
size;
msgId;
arrivalTime;
arrivalTimeString;
bodyBuffer;
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
/* Caller must set IM_Msg::msgRef. */
int IM_InitMsg (IM_Msg*);
int IM_FreeMsg (IM_Msg*);
int
int
int
int
int
int
int
IM_ReadMsg (IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);
IM_CreateMsg(IM_Mbox*, IM_Folder*, const char* from,
cons char* text, IM_Msg*, IM_Error*);
IM_DeleteMsg(IM_Mbox*, IM_Folder*, IM_Msg*, IM_Error*);
IM_ReadMsgHeader(IM_Mbox*, IM_Folder*, IM_Msg*,
const char* hdrLabel, char** hdrValue, IM_Error*);
IM_ReadMsgBody(IM_Mbox*, IM_Folder*, IM_Msg*,
offset, int size, char** text, IM_Error*);
IM_UpdateMsgFlags(IM_Mbox*, IM_Folder*, IM_Msg*,
const char* flags, IM_Error*);
,0B5HDG0VJ
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.
,0B&UHDWH0VJ
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 RFC822formatted message, including headers. No syntax checking is performed on this text.
On success, the msgRef field of the IM_Msg argument will be set.
,0B'HOHWH0VJ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
321
InterMail Kx Reference Guide
,0B5HDG0VJ+HDGHU
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.
,0B5HDG0VJ%RG\
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.
,0B8SGDWH0VJ)ODJV
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:
322
Position 0
RECENT
Position 1
SEEN
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
Position 2
ANSWERED
Position 3
FLAGGED
Position 4
DRAFT
Position 5
DELETED
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
IM_REPLYMSG_AUTOREPLY
IM_REPLYMSG_SIGNATURE
IM_REPLYMSG_ADDRESSBOOK
IM_REPLYMSG_GREENLIST
IM_REPLYMSG_USERFILTER
=
=
=
=
=
=
0,
1,
2,
3,
4,
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:
_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.
Confidential and Proprietary, © Software.com, Inc. 1999
323
InterMail Kx Reference Guide
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 autoreply 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.
int IM_InitReply(IM_Reply*);
int IM_FreeReply(IM_Reply*);
int
int
int
int
IM_CreateReply(IM_Account*,
IM_ReadReply (IM_Account*,
IM_UpdateReply(IM_Account*,
IM_DeleteReply(IM_Account*,
IM_Reply*, IM_Error*);
IM_Reply*, IM_Error*);
IM_Reply*, IM_Error*);
IM_Error*);
,0B&UHDWH5HSO\
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.
,0B5HDG5HSO\
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.
324
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
,0B8SGDWH5HSO\
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.
,0B'HOHWH5HSO\
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 Service
Interface: 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
{
int
num;
IM_ServiceAttr*
attrs;
} IM_ServiceDef;
typedef struct IM_Cos
{
IM_Header
char*
IM_ServiceDef
/*Located in im_defs.h */
_header;
name;
serviceDef;
Confidential and Proprietary, © Software.com, Inc. 1999
325
InterMail Kx Reference Guide
} 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:
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
The syntax field can take one of the following values:
IM_ATTR_SYNTAX_STRING
Null-Terminated String
IM_ATTR_SYNTAX_NUMERIC
Integer
IM_ATTR_SYNTAX_BOOLEAN
Boolean (True/False)
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*);
326
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
int
IM_FreeCosAttrDefArray(IM_CosAttrDefArray*);
int
int
int
int
IM_CreateCos(IM_Cos*, IM_Error*);
IM_DeleteCos(IM_Cos*, IM_Error*);
IM_ReadCosNames(IM_StringArray*, IM_Error*);
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
int
int
int
IM_CreateCosAttribute(IM_CosAttrDef*, IM_Error*);
IM_UpdateCosAttribute(IM_CosAttrDef*, IM_Error*);
IM_DeleteCosAttribute(IM_CosAttrDef*, IM_Error*);
IM_ReadCosAttributes(IM_CosAttrDefArray*, IM_Error*);
,0B&UHDWH&RV
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.
,0B'HOHWH&RV
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.
,0B5HDG&RV1DPHV
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.
,0B5HDG&RV
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.
Confidential and Proprietary, © Software.com, Inc. 1999
327
InterMail Kx Reference Guide
,0B6HW&RV$WWULEXWH
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
,0B8QVHW&RV$WWULEXWH
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
,0B&UHDWH&RV$WWULEXWH
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_.
,0B8SGDWH&RV$WWULEXWH
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.
328
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
,0B'HOHWH&RV$WWULEXWH
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.
,0B5HDG&RV$WWULEXWHV
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 Information
Interface: im_config.h
typedef struct IM_Config
{
IM_Header _header;
char*
name;
char*
host;
char*
prog;
char*
defvalue;
char*
value;
} IM_Config;
The fields of this structure and their syntax are:
_header
Internal use.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
329
InterMail Kx Reference Guide
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.
int IM_InitConfig(IM_Config*);
int IM_FreeConfig(IM_Config*);
int IM_ReadConfig(IM_Config*, IM_Error*);
,0B,QLW&RQILJ
int IM_InitConfig(IM_Config*)
This function initializes an IM_Config structure.
,0B)UHH&RQILJ
int IM_FreeConfig(IM_Config*)
This function frees the IM_InitConfig structure.
,0B5HDG&RQILJ
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 Information
Interface: 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;
330
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
char*
char*
char*
char*
char*
char*
char*
IM_StringArray
IM_StringArray
IM_StringArray
} IM_MimeInfo;
contentTransferEncoding;
mainContentType;
subContentType;
contentId;
contentDescription;
boundary;
contentMD5;
contentDisposition;
contentLanguage;
parameters;
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.
The fields of this structure and their syntax are:
_header
Internal use.
_internalID
Internal use.
_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.
Confidential and Proprietary, © Software.com, Inc. 1999
331
InterMail Kx Reference Guide
332
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 ContentDisposition 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: ContentDisposition: attachment; filename=x is
returned as the three-element array
(attachment, filename, x).
contentLanguage
A string array describing the ContentLanguage 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.
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
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).
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*);
,0B,QLW0LPH,QIR
int IM_InitMimeInfo(IM_MimeInfo*);
This function initializes the IM_MimeInfo structure.
,0B)UHH0LPH,QIR
int
IM_FreeMimeInfo(IM_MimeInfo*);
This function frees the IM_MimeInfo structure.
,0B5HDG0VJ0LPH,QIR
int
IM_ReadMsgMimeInfo(IM_Mbox*, IM_Folder*, IM_Msg*,
IM_MimeInfo* parent, int index, IM_MimeInfo* output,
IM_Error*);
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.
Confidential and Proprietary, © Software.com, Inc. 1999
333
InterMail Kx Reference Guide
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.
void
dumpSubMimeInfo(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);
334
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
}
}
void
dumpMimeInfo(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 Messages
This 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;
Confidential and Proprietary, © Software.com, Inc. 1999
335
InterMail Kx Reference Guide
The information about log messages is conveyed via the structure IM_LogMsg:
_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.
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);
336
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
,0B,QLW/RJ0VJ
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.
,0B)UHH/RJ0VJ
int IM_FreeLog Msg(IM_LogMsg* logmsg);
Free the IM_LogMsg structure.
,0B&UHDWH/RJ)LOH
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-dateand-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.
,0B:ULWH/RJ0VJ
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.
,0B5HDG/RJ0VJ7H[W
int IM_ReadLogMsgText(IM_LogMsg* logmsg, IM_Error* error);
Formats a log message and returns it in the text field of the logmsg.
Log Context
This 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;
Confidential and Proprietary, © Software.com, Inc. 1999
337
InterMail Kx Reference Guide
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:
338
_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.
Confidential and Proprietary, © Software.com, Inc. 1999
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
,0B,QLW/RJ&RQWH[W
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.
,0B)UHH/RJ&RQWH[W
int IM_FreeLogContext(IM_LogContext* logc);
Free the IM_LogContext structure.
,0B8SGDWH/RJ&RQWH[W
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.
,0B5HDG/RJ&RQWH[W
int IM_ReadLogContext(IM_LogContext* logctx, IM_Error*
error);
Read the current log context and save the context information in logctx.
Confidential and Proprietary, © Software.com, Inc. 1999
339
InterMail Kx Reference Guide
Compiling, Linking, and Running
InterMail 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.6
To 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 \
340
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail C API
Digital UNIX
To 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 6
To 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 Summary
The following is a list of the InterMail C-API header files:
im_account.h
im_config.h
im_cos.h
im_defs.h
im_domain.h
im_error.h
im_folder.h
im_log.h
im_mbox.h
im_msg.h
im_reply.h
im_stringarray.h
im_types.h
InterMail API libraries:
libim.so (link to libim.4. x)
libomu.so (link to libomu.4.x)
Confidential and Proprietary, © Software.com, Inc. 1999
341
InterMail Kx Reference Guide
Function Summary
The 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*);
342
Confidential and Proprietary, © Software.com, Inc. 1999
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);
Confidential and Proprietary, © Software.com, Inc. 1999
343
InterMail Kx Reference Guide
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*);
344
Confidential and Proprietary, © Software.com, Inc. 1999
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*);
int IM_ReadMsgMimeInfo(IM_Mbox*, IM_Folder*, IM_Msg*,
IM_MimeInfo* parent, int index, IM_MimeInfo* output,
IM_Error*);
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*);
Confidential and Proprietary, © Software.com, Inc. 1999
345
InterMail Kx Reference Guide
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*);
346
Confidential and Proprietary, © Software.com, Inc. 1999
6
InterMail 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
Introduction
The 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.
Confidential and Proprietary, © Software.com, Inc. 1999
347
InterMail Kx Reference Guide
General Usage Notes
Due 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 Scripts
To 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.
348
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
Underlying Libraries and Versioning
A 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 runtime 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?;
}
Confidential and Proprietary, © Software.com, Inc. 1999
349
InterMail Kx Reference Guide
Error Handling
Most 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 Objects
This 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’,
...
);
350
Confidential and Proprietary, © Software.com, Inc. 1999
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(...)
Confidential and Proprietary, © Software.com, Inc. 1999
351
InterMail Kx Reference Guide
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 Reference
Description
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 Reference
Description
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.
352
Confidential and Proprietary, © Software.com, Inc. 1999
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.
Confidential and Proprietary, © Software.com, Inc. 1999
353
InterMail Kx Reference Guide
•
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 Reference
This section describes the attributes and methods of all classes in the InterMail Perl
API.
CosAttribute
The class CosAttribute (Class of Service Attribute) has the following fields:
id
Integer
name
String. All CosAttribute names must begin with a prefix of
“perm_” or “pref_”.
rule
enum IM_AttributeRule (see
syntax
enum IM_AttributeSyntax
Chapter 5)
(see Chapter 5)
A new CosAttribute object can be created this way:
$cos = new
name
rule
syntax
};
CosAttribute(
=> ′pref_quota′,
=> IM_ATTR_RULE_COS_OVERRIDES,
=> 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.
354
Confidential and Proprietary, © Software.com, Inc. 1999
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:
5HDG$OO
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.
&UHDWH
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.
'HOHWH
Prerequisites
The name field must refer to an existing CosAttribute.
Implementation
Calls IM_DeleteCosAttribute().
Confidential and Proprietary, © Software.com, Inc. 1999
355
InterMail Kx Reference Guide
Return Values
Returns “1” on success, “0” on failure.
8SGDWH
Prerequisites
The name field must refer to an existing CosAttribute.
Implementation
Calls IM_UpdateCosAttribute().
Return Values
Returns “1” on success, “0” on failure.
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();
Cos
The class Cos (Class of Service) has the following fields:
name
String
serviceDef
Reference to associative array of Class of Service (COS) values
A new Cos object can be created this way:
my $cos = new Cos(
name
=> ′basic′,
serviceDef => {
356
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
pref_quotatotkb
pref_quotathreshold
pref_pop
pref_imap
pref_intermanager
=>
=>
=>
=>
=>
′10000’,
′80′,
′1′,
′1′,
′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:
5HDG1DPHV
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.
&UHDWH
Prerequisites
The name field must be defined and not already in use by a previous created Cos.
Implementation
Calls IM_CreateCos().
Return Values
Returns “1” on success, “0” on failure.
5HDG
Prerequisites
The name field must refer to an existing Cos.
Confidential and Proprietary, © Software.com, Inc. 1999
357
InterMail Kx Reference Guide
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.
6HW$WWULEXWHDWWUBQDPHDWWUBYDOXH
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.
8QVHW$WWULEXWHDWWUBQDPH
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.
'HOHWH
Prerequisites
The name field must refer to an existing Cos.
Calls IM_DeleteCos().
Return Values
Returns “1” on success, “0” on failure.
Example
my @name_list = Cos::ReadNames();
358
Confidential and Proprietary, © Software.com, Inc. 1999
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();
Domain
The class Domain has the following attributes (fields):
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
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.
Confidential and Proprietary, © Software.com, Inc. 1999
359
InterMail Kx Reference Guide
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):
/LVWIURPWLOOPD[
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
my
my
my
$max = 100;
$from = ′′; # Start at the lowest possible name.
$till = ′′; # Continue to the highest possible name.
@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.
}
360
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
/LVW6XE'RPDLQVWRS'RPDLQIURPWLOOPD[
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
my
my
my
my
$topdomain = ′example.com′;
$max = 100;
$from = ′′; # Start at the lowest possible name.
$till = ′′; # Continue to the highest possible name.
@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.
}
Confidential and Proprietary, © Software.com, Inc. 1999
361
InterMail Kx Reference Guide
&UHDWH
Prerequisites
The fields name must be defined and valid.
Implementation
Calls IM_CreateDomain().
Return Values
Returns “1” on success, “0” on failure.
5HDG
Prerequisites
The field name must be defined and valid.
Implementation
Calls IM_ReadDomain().
Return Values
Returns “1” on success, “0” on failure.
8SGDWH
Prerequisites
The field name must be defined and valid.
Implementation
Calls IM_UpdateDomain().
Return Values
Returns “1” on success, “0” on failure.
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:
362
When Update() specifies a wildcard account, the user must use only the
local portion of the SMTP address.
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
'HOHWH
Prerequisites
The field name must be defined and valid.
Implementation
Calls IM_DeleteDomain().
Return Values
Returns “1” on success, “0” on failure.
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();
Account
The 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)
Confidential and Proprietary, © Software.com, Inc. 1999
363
InterMail Kx Reference Guide
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)
A new Account object can be created in the following manner:
$account=new Account(
smtpAddress
=> ′john.doe@example.com′,
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):
&UHDWH
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
364
Confidential and Proprietary, © Software.com, Inc. 1999
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
Returns “1” on success, “0” on failure.
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.
5HDG
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
Returns “1” on success, “0” on failure.
If the call succeeds, all fields of the Perl object will be set from the InterMail
Directory.
8SGDWH
Prerequisites
The field smtpAddress must be defined and valid.
Implementation
Calls IM_UpdateAccount().
Return Values
Returns “1” on success, “0” on failure.
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
Confidential and Proprietary, © Software.com, Inc. 1999
365
InterMail Kx Reference Guide
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.
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().
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 => "joe.bloe@example.com");
$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();
8SGDWH$GGUQHZ6PWS$GGUHVV
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
Returns “1” on success, “0” on failure.
Only the primary SMTP address of the account is altered by this function.
366
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
'HOHWH
Prerequisites
The field smtpAddress must be defined and valid.
Implementation
Calls IM_DeleteAccount().
Return Values
Returns “1” on success, “0” on failure.
&UHDWH$OLDVDGGU
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
Returns “1” on success, “0” on failure.
'HOHWH$OLDVDGGU
Prerequisites
The addr argument must refer to an existing alias for this account.
Implementation
Calls IM_DeleteAlias();.
Return Values
Returns “1” on success, “0” on failure.
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);
Confidential and Proprietary, © Software.com, Inc. 1999
367
InterMail Kx Reference Guide
5HDG$OLDVHV
Prerequisites
The field smtpAddress must be defined and valid.
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 = ′john.doe@example.com′;
$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);
&UHDWH)RUZDUGDGGU
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
Returns “1” on success, “0” on failure.
368
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
'HOHWH)RUZDUGDGGU
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
Returns “1” on success, “0” on failure.
5HDG)RUZDUGV
Prerequisites
The field smtpAddress must be defined and valid.
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=“john.doe@example.com”;
$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.
Confidential and Proprietary, © Software.com, Inc. 1999
369
InterMail Kx Reference Guide
(QDEOH)RUZDUGLQJ
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
Returns “1” on success, “0” on failure.
'LVDEOH)RUZDUGLQJ
Prerequisites
The field smtpAddress must be defined and valid.
Implementation
Calls IM_DisableAccountForwards().
Return Values
Returns “1” on success, “0” on failure.
$account->EnableForwarding();
...
$account->DisableForwarding();
5HDG$OLDV
Prerequisites
The field smtpAddress must be defined and valid.
Implementation
Calls IM_ReadAlias().
Return Values
Returns “1” on success, “0” on failure.
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.
370
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
5HDG323
Prerequisites
The field popAddress must be defined and valid.
Implementation
Calls IM_ReadPOP3().
Return Values
Returns “1” on success, “0” on failure.
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 cat@example.com
$alias=“kitty@example.com”;
$pop=“katze”;
$account=new Account(popAddress => “hound”);
$account->ReadPOP3();
# The fields will now be:
# smtpAddress=>“dog@example.com”, popAddress=>“hound”
$account->smtpAddress(“kitty@example.com”);
$account->ReadAlias();
# The fields will be now:
#
smtpAddress=>“cat@example.com”, popAddress=>“katze”
/LVWGRPDLQIURPWLOOPD[
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
Confidential and Proprietary, © Software.com, Inc. 1999
371
InterMail Kx Reference Guide
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
my
my
my
my
$domain = ′example.com′;
$max = 100;
$from = ′′; # Start at the lowest possible name.
$till = ′′; # Continue to the highest possible name.
@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.
}
+DVK3DVVZRUGSDVVZRUGKDVK7\SH
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.
&KHFN3DVVZRUGSDVVZRUGKDVKHG3DVVZRUGKDVK7\SH
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.
372
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
Mailbox
The class Mailbox has the following attributes (fields):
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
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.
Confidential and Proprietary, © Software.com, Inc. 1999
373
InterMail Kx Reference Guide
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=>“johnd@example.com”);
# 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):
374
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
&UHDWHPHVVDJH,G
Prerequisites
The account field must reference a valid Account object, with emailIntID and
mssHost set.
Implementation
Calls IM_CreateMailbox().
Return Values
Returns “1” on success, “0” on failure.
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.
5HDG
Prerequisites
The account field must reference a valid Account object, with the emailIntID and
mssHost fields set.
Implementation
Calls IM_ReadMailbox().
Return Values
Returns “1” on success, “0” on failure.
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.
'HOHWH
Prerequisites
The account field must reference a valid Account object, with the emailIntID and
mssHost fields set.
Implementation
Calls IM_DeleteMailbox().
Return Values
Returns “1” on success, “0” on failure.
Deletes the mailbox record in the InterMail database.
Confidential and Proprietary, © Software.com, Inc. 1999
375
InterMail Kx Reference Guide
Example
# Construct an account object without specifying
# any information but the ″key″:
$account=new Account(smtpAddress=>“john@example.com”);
# 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″
376
Confidential and Proprietary, © Software.com, Inc. 1999
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();
LPBVHW066&RQQ3RRO6L]HVL]H
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.
Folder
The 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
Confidential and Proprietary, © Software.com, Inc. 1999
377
InterMail Kx Reference Guide
UIDValidity
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):
&UHDWH
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_CreateFolder().
Return Values
Returns “1” on success, “0” on failure.
5HDG
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_ReadFolder().
Return Values
Returns “1” on success, “0” on failure.
378
Confidential and Proprietary, © Software.com, Inc. 1999
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.
5HQDPHQHZBQDPH
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_RenameFolder().
Return Values
Returns “1” on success, “0” on failure.
Renames the folder to the new_name.
'HOHWH
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_RenameFolder().
Return Values
Returns “1” on success, “0” on failure.
'HOHWH0HVVDJHVPVJV«
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_DeleteFolderMsgs().
Return Values
Returns “1” on success, “0” on failure.
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
Confidential and Proprietary, © Software.com, Inc. 1999
379
InterMail Kx Reference Guide
array of Messages instead of individual Messages. This function is more efficient than
deleting the messages one by one.
6FDQ0HVVDJHVPVJV«
Prerequisites
The mailbox and pathname fields must be defined and valid.
Implementation
Calls IM_ScanFolderMsgs().
Return Values
Returns “1” on success, “0” on failure.
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′);
380
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
print_status();
print $folder_f1_f2->Dump();
$folder_f1_f2->Delete();
0RYH0HVVDJHVGVW)ROGHUPVJ5HIV«
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
Returns “1” on success, “0” on failure.
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.
&RS\0HVVDJHVGVW)ROGHUPVJ5HIV«
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
Returns “1” on success, “0” on failure.
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.
Message
The class Message has the following attributes (fields):
mailbox
Reference to a Mailbox object
folder
Reference to a Folder object
msgRef
Integer
Confidential and Proprietary, © Software.com, Inc. 1999
381
InterMail Kx Reference Guide
msgId
String
size
Integer
seen
Integer
arrivalTime
Integer
arrivalTimeString
String
UID
Integer
flags
String
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):
&UHDWHIURPWH[W
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
Returns “1” on success, “0” on failure.
If the call is successful fills in the field msgRef.
382
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
5HDG
Prerequisites
The mailbox, folder and msgRef fields must be defined and valid.
Implementation
Calls IM_ReadMsg().
Return Values
Returns “1” on success, “0” on failure.
Fills in the values of all fields of the object by retrieving the information from the
InterMail database.
5HDG+HDGHUILHOG
Prerequisites
The mailbox, folder and msgRef fields must be defined and valid.
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.
5HDG&RQWHQWRIIVHWVL]H
Prerequisites
The mailbox, folder and msgRef fields must be defined and valid.
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.
'HOHWH
Prerequisites
The mailbox, folder and msgRef fields must be defined and valid.
Implementation
Calls IM_DeleteMsg().
Confidential and Proprietary, © Software.com, Inc. 1999
383
InterMail Kx Reference Guide
Return Values
Returns “1” on success, “0” on failure.
8SGDWH)ODJVIODJV
Prerequisites
The mailbox, folder and msgRef fields must be defined and valid.
Implementation
Calls IM_UpdateMsgFlags().
Return Values
Returns “1” on success, “0” on failure.
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 = “cat@example.com”;
$text = <<′EndOfMessage′
From: cat
To: 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();
384
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
Reply
The class Reply has the following attributes (fields):
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 userdefined reply types.
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...′
);
&UHDWH
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
Returns “1” on success, “0” on failure.
Confidential and Proprietary, © Software.com, Inc. 1999
385
InterMail Kx Reference Guide
5HDG
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
Returns “1” on success, “0” on failure.
8SGDWH
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
Returns “1” on success, “0” on failure.
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().
'HOHWH
Prerequisites
The field account must be defined and valid.
Implementation
Calls IM_DeleteReply().
Return Values
Returns “1” on success, “0” on failure.
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.′
386
Confidential and Proprietary, © Software.com, Inc. 1999
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.
ConfigItem
The class ConfigItem has the following attributes (fields):
name
String
host
String
prog
String
defvalue
String
value
String
A new ConfigItem object can be created this way:
$config = new ConfigItem(
name => ’netTimeout’,
host => ’paris’,
prog => ’mta’,
defvalue => ′60′
);
Confidential and Proprietary, © Software.com, Inc. 1999
387
InterMail Kx Reference Guide
5HDG
Prerequisites
The name field must be set.
Implementation
Calls IM_ReadConfig().
Return Values
Returns “1” on success, “0” on failure.
MimeInfo
The class MimeInfo has the following attributes (fields):
388
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
Confidential and Proprietary, © Software.com, Inc. 1999
InterMail Perl API
parameters
Array of strings
5HDG0LPH,QIRPLPH>SDUHQW>LQGH[@@
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
Returns “1” on success, “0” on failure.
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);
}
}
}
Confidential and Proprietary, © Software.com, Inc. 1999
389
InterMail Kx Reference Guide
LogMsg
Objects of type LogMsg have the following attributes:
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
A new LogMsg object can be created this way:
$logmsg = new LogMsg(
severity => IM_SEVERITY_ERROR,
type => ′FioCreateFail′,
args => [ $filename ]
);
&UHDWH)LOH
Prerequisites
logName must be set to a valid filename containing no “/” characters. Other attributes
are ignored.
Implementation
Calls IM_CreateLogFile().
Return Values
Returns “1” on success, “0” on failure.
:ULWH
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
Returns “1” on success, “0” on failure.
390
Confidential and Proprietary, © Software.com, Inc. 1999
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 ]);
5HDG7H[W
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).
LogContext
Objects 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
Confidential and Proprietary, © Software.com, Inc. 1999
391
InterMail Kx Reference Guide
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
A new LogContext object can be created this way:
$logmsg = new LogContext(
mailUser => $userName,
folder => $folderName,
cmd => $commandName
);
8SGDWH
Prerequisites
None.
Implementation
Calls IM_UpdateLogContext().
Return Values
Returns “1” on success, “0” on failure.
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.
5HDG
Prerequisites
None.
Implementation
Calls IM_ReadLogContext().
Return Values
Returns “1” on success, “0” on failure.
The values from the global logging context will be stored into the LogContext object,
replacing any values that were previously stored there.
392
Confidential and Proprietary, © Software.com, Inc. 1999
7
InterManager 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.
Introduction
The 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 Classes
This 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
Confidential and Proprietary, © Software.com, Inc. 1999
393
InterMail Kx Reference Guide
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 Classes
The following sections describe the individual API classes contained in the
InterManager Perl API.
SwCom::Error
Description
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
394
•
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.
Confidential and Proprietary, © Software.com, Inc. 1999
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::WebSession
Description
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, 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.
Confidential and Proprietary, © Software.com, Inc. 1999
395
InterMail Kx Reference Guide
•
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::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();
396
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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::WebSession::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 constructor. Returns the LDAP session descriptor on success, otherwise undef.
•
RootBind()
Binds to the LDAP server as “Root”. Returns the LDAP session descriptor on success, 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 reference to the recipient object and it must implement the GetError() SetError() methods. (See WebSession::GetError() and
WebSession::SetError()). Prior to storing the new object reference, the SetError() 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::Session::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.
Confidential and Proprietary, © Software.com, Inc. 1999
397
InterMail Kx Reference Guide
•
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::SetErrorDst(). 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);
398
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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 InterManager 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 construct 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 routine. Call this routine using its fully qualified name. For example,. if DN is:
uid=abc@xyz.com,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:
uid=abc@xyz.com,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
Confidential and Proprietary, © Software.com, Inc. 1999
399
InterMail Kx Reference Guide
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’, representing “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 otherwise.
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’]},
}
•
400
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
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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 ();
Confidential and Proprietary, © Software.com, Inc. 1999
401
InterMail Kx Reference Guide
$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
402
•
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.
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
•
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 organizational units and users; ordinary users will not. Returns true on success, undef otherwise. 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 success, 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 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—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
Confidential and Proprietary, © Software.com, Inc. 1999
403
InterMail Kx Reference Guide
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: objectclass, 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 organization 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=worldnet,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.
404
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
ie:
[a,
[a,
[a,
[a,
)
( [a],
m],
n],
n, x],
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 => {}}, ...} preserving 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::OrgUnit
Description
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.
Confidential and Proprietary, © Software.com, Inc. 1999
405
InterMail Kx Reference Guide
Synopsis
$org_unit
$ou_name,
$org_unit
$ou_name,
$org_unit
$ou_name,
$org_unit
= new SwCom::IMgr::OrgUnit(IMgrSession, $org,
...);
= new_from_org SwCom::IMgr::OrgUnit(IMgrOrg,
...);
= new_from_ou SwCom::IMgr::OrgUnit(IMgrOrgUnit,
...);
= 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
•
Constructors
Constructors 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.
406
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
$org_unit = new_from_dn (IMgrSession, $dn)
The fourth form, requires a SwCom::IMgr::Session and the full DN of an organization 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 organizational 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 otherwise.
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 Organizational 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 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.
•
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, ... )
Confidential and Proprietary, © Software.com, Inc. 1999
407
InterMail Kx Reference Guide
Removes persons from the OU administrators’ group object, i.e. revokes an
administrative role for persons over this OU. Currently ‘role’ is ignored. All persons are removed from the Organizational Unit administrative group. The persons
passed in are SwCom::IMgr::Person objects. Returns 1 on success, undef otherwise.
•
GetAdmins( role, ... )
Returns a list of SwCom::IMgr::Person objects corresponding to the OU administrators. 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::Person
Description
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();
408
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
$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:
•
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.
new_from_mailgroup SwCom::IMgr::Person ( parent, name, IMgrMailGroup)
Constructor for the IMgrPerson. Returns a reference to a SwCom::IMgr::Person object.
where:
•
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.
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.)
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.
Confidential and Proprietary, © Software.com, Inc. 1999
409
InterMail Kx Reference Guide
where:
IMgrSession
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.
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 Distinguished 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 person. 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 values 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
410
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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: smtpAddress, 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 reference 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-
Confidential and Proprietary, © Software.com, Inc. 1999
411
InterMail Kx Reference Guide
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 otherwise.
Restrictions—a user can not remove values from the following attributes:
objectclass, uid, mail, mailgroup, allowedservices, preferredservices; 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: objectclass, uid, allowedservices.
•
Roles()
NOT YET IMPLEMENTED.
•
GetAdminAuthority()
Returns a hash mapping an administrative role to those entries upon which the person 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:
uid=joe.bloe@venus.software.com,ou=dev,ou=west,ou=eng,dc=accordance,dc=com
the list returned is: eng, west, dev
•
412
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.
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
SwCom::IMgr::MailGroup
Description
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, IMgrMailCOS);
$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
Confidential and Proprietary, © Software.com, Inc. 1999
413
InterMail Kx Reference Guide
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.
414
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
•
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: objectclass, 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.
Confidential and Proprietary, © Software.com, Inc. 1999
415
InterMail Kx Reference Guide
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.
•
416
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
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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 referencing 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.
•
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 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 calling 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 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 values on the LDAP entry are a valid key in the returned hash, mapped to the undef
Confidential and Proprietary, © Software.com, Inc. 1999
417
InterMail Kx Reference Guide
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 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,
mup, mail, mailid; and the InterMail API attributes: smtpAddress, emailIntID.
•
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: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.
SwCom::IMgr::MailCOS
Description
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( IMgrProvider, $cos_name );
$cos = new_from_dn SwCom::IMgr::MailCOS( IMgrSession, $dn
);
$name = $cos->Name();
$cos ->SetProperties(’attr’ => val, ...);
$cos ->Create(’attr’ => val, ...);
418
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
$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.
•
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 MailCOSExists, LdapEntryExists each which take values 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 OnMailCOSExistence 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 OnLdapExistence is set to fail_if_exists, an error is returned (undef), otherwise if set
to ok_if_exists.
Confidential and Proprietary, © Software.com, Inc. 1999
419
InterMail Kx Reference Guide
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 property 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().
Returns 1 on success, undef otherwise.
•
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.
Returns 1 on success, undef otherwise.
Note:
•
420
Class of service attributes cannot be modified using Add. Use SetAttributes 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.
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
Restrictions—a user can not remove values from the following attributes:
objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress,
emailIntID.
Returns 1 on success, undef otherwise.
•
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: objectclass, mup, mail, mailid; and the Mail API attributes: smtpAddress, emailIntID.
Returns 1 on success, undef otherwise.
SwCom::IMgr::Provider
Description
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();
Confidential and Proprietary, © Software.com, Inc. 1999
421
InterMail Kx Reference Guide
$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 Organization entry is distinguished by its businesscategory attribute, which contains 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 pertaining 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.
Returns 1 on success, undef otherwise.
•
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.
422
•
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 organization.
•
AddAdmins( role, ImgrPerson, ... );
Grants an administrative role over this Provider to Persons. Role is ’site admin’,
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
'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.
Returns 1 on success, undef otherwise.
•
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.
Returns undef in case of an error.
•
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.)
Returns undef in case of an error.
•
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()
Confidential and Proprietary, © Software.com, Inc. 1999
423
InterMail Kx Reference Guide
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::AdminGroup(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:
•
424
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-
Confidential and Proprietary, © Software.com, Inc. 1999
InterManager Perl API
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 belonging to the admin group. Returns undef in case of an error.
SwCom::IMgr::Domain
Description
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.
•
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.
Confidential and Proprietary, © Software.com, Inc. 1999
425
InterMail Kx Reference Guide
Valid properties are MailDomainExists, which takes values 1 or 0; OnMailDomainExistence, 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 OnMailDomainExistence 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 argument 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.
•
426
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.
Confidential and Proprietary, © Software.com, Inc. 1999
8
LDAP 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_open
ldap_simple_bind_s
ldap_unbind
•
Functions that perform operations on entries:
ldap_add_s
ldap_modify_s
ldap_delete_s
ldap_modrdn_s
ldap_rename_s
ldap_search_s
ldap_count_entries
ldap_get_all_entries
•
Access Control Information function:
ldap_apply_aci_rule_s
•
Memory management function:
ldap_msgfree
Confidential and Proprietary, © Software.com, Inc. 1999
427
InterMail Kx Reference Guide
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 call
my $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.
428
Confidential and Proprietary, © Software.com, Inc. 1999
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
429
InterMail Kx Reference Guide
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
dn: Distinguished name (DN) of the entry to be deleted.
430
Confidential and Proprietary, © Software.com, Inc. 1999
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
431
InterMail Kx Reference Guide
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:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
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:
ld: Connection handle returned by ldap_open.
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.
432
Confidential and Proprietary, © Software.com, Inc. 1999
LDAP Perl API
Example:
$count=ldap_count_entries($ld,$result);
print "\$count=$count\n";
ldap_get_all_entries(ld, result)
Returns:
An LDAP status code.
Parameters:
ld: Connection handle returned by ldap_open.
result: Opaque pointer returned by a previous call to ldap_search_s.
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 Function
Access 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_s
Parameters:
ld: Connection handle returned by ldap_open.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
433
InterMail Kx Reference Guide
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:
An LDAP status code.
Parameters:
result: Opaque pointer returned by a previous call to ldap_search_s.
Description:
Frees memory associated with a result returned by ldap_search_s.
Example:
$rc = ldap_msgfree($result)
434
Confidential and Proprietary, © Software.com, Inc. 1999
9
Log 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.
•
•
Cause: The specific reason(s) why an event occurred.
•
Actions: The suggested course of action to correct the problem, or an action to
minimize the effect of the problem.
Description: A short synopsis of the message.
Parameters: Parameters, arguments, or variable names in the description of the
event.
Effect: The effect that an event has on the operation of InterMail, including the
severity level.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
435
InterMail Kx Reference Guide
Account Log Events
$FFW%DG3VZG
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
user=Suzie.Queue@domain.com. 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.
$FFW%DG3VZG0D[
436
Description:
Maximum invalid password attempts from user.
Parameters:
None.
Cause:
None.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
$FFW%DG3VZG0D[$GGUV
Description:
Reached maximum number of IP addresses making invalid password
attempts.
Parameters:
None.
Cause:
None.
Effect:
The event is of informational severity.
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.
$FFW%DG3VZG0D['HOD\
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.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
437
InterMail Kx Reference Guide
$FFW%DG3VZG0D[)DLOXUHV
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.
Effect:
The event is of informational severity.
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.
$FFW%DG3VZG0D[8VHUV
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.
Effect:
The event is of informational severity.
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.
$FFW'LU&DFKH'RZQ
438
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
$FFW'LU&DFKH(UURU
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.
$FFW'LU&DFKH8QNQRZQ(UURU
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.
Confidential and Proprietary, © Software.com, Inc. 1999
439
InterMail Kx Reference Guide
$FFW)RUZDUG,QIR,QYDOLG
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.
$FFW)RUZDUG,QIR0LVVLQJ
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.
$FFW)RUZDUG,QIR4XHU\)DLO
440
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
$FFW)RUZDUG7R
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.
Effect:
The event is of warning severity.
Action(s):
Check to make sure all executables are the original versions as installed.
$FFW,PDS1RW$OORZHG
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user has authorization to use IMAP.
$FFW,QDFWLYH
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.
Effect:
The event is of warning severity.
Action(s):
Contact the mail system administrator to find out why the mailbox is
inactive.
Confidential and Proprietary, © Software.com, Inc. 1999
441
InterMail Kx Reference Guide
$FFW,QYDOLG8VHU
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.
Effect:
The event is of informational severity.
Action(s):
None.
$FFW/RRNXS)DLO
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.
$FFW0DLQWHQDQFH
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.
Effect:
The event is of informational severity.
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.
442
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
$FFW1RQWUXVWHG/RJLQ
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.
Effect:
The event is of informational severity.
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.
$FFW1RW8VHU
Description:
UserName does not exist in the Integrated Services Directory.
Parameters:
None.
Cause:
The userName is not in the Integrated Services Directory, and thus is not
valid at this site.
Effect:
The event is of informational severity.
Action(s):
None.
$FFW2WKHU)DLOXUH
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.
Effect:
The event is of warning severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
443
InterMail Kx Reference Guide
$FFW3RS)LOWHU6\QWD[,QYDOLG5HJH[
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.
$FFW3RS)LOWHU6\QWD[0LVVLQJ6HSDUDWRU
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.
444
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
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
$FFW3RS)LOWHU6\QWD[0LVVLQJ6WDUW
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.
$FFW3RS1RW$OORZHG
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user has authorization to use the POP server.
$FFW3VZG%DG
Description:
The user is entering an invalid password.
Parameters:
None.
Cause:
A user is entering a bad password for his or her mail account.
Effect:
The event is of warning severity.
Action(s):
Usually there is nothing to do. The user eventually remembers his or her
password or gets a new one.
Confidential and Proprietary, © Software.com, Inc. 1999
445
InterMail Kx Reference Guide
$FFW6VO,PDS1RW$OORZHG
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user is authorized to use imap with SSL.
$FFW66/3RS1RW$OORZHG
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user has authorization to use SSL with the POP server.
$FFW8QNQRZQ8VHU
446
Description:
UserName does not exist in the Integrated Services Directory.
Parameters:
None.
Cause:
The userName is not in the Integrated Services Directory, and thus is not
valid at this site.
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
Configuration Log Events
&RQI%DG&KHFNVXP
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.
Confidential and Proprietary, © Software.com, Inc. 1999
447
InterMail Kx Reference Guide
&RQI%DG.H\
Description:
There is a bad key in the configuration file.
Parameters:
badKey: the bad key in the configuration file.
filename: the path to 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.
Effect:
The event is of critical severity.
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.
&RQI&KDQJH$VVHVVPHQW
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.
&RQI&KDQJH,QVWDOO
448
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI&OLHQW&RQQHFW
Description:
Parameters:
A client program is connecting to the configuration server.
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.
&RQI&RPPRQ3RUW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
449
InterMail Kx Reference Guide
&RQI&RPPRQ3RUW5DQJH
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.
&RQI'XSOLFDWH.H\
Description:
There is a bad key in the configuration file.
Parameters:
badKey: the bad key in the configuration file.
filename: the path to 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 ///. Key components consist only of letters,
numbers, and the characters /, ., and _. The component can also be *
(meaning all hosts). The component violates this rule.
450
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.
Action(s):
Fix the configuration file manually using a text editor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI(QG8SGDWH
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 nonzero, 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.
&RQI)L[HU)XQF)DLOHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
451
InterMail Kx Reference Guide
&RQI)RXQG2WKHU066
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.
&RQI,QVWDOO)DLOHG
452
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.
Effect:
The event is of critical severity.
Action(s):
Read the imconfserv log to find out what the problems are.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI,QVWDOO6XFFHHGHG
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.
&RQI,QYDOLG+RVW1DPH
Description:
There is a bad key in the configuration file.
Parameters:
badKey: the bad key in the configuration file.
filename: the path to 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 ///. 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.
Effect:
The event is of critical severity.
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.
Action(s):
Fix the configuration file manually using a text editor.
Confidential and Proprietary, © Software.com, Inc. 1999
453
InterMail Kx Reference Guide
&RQI,QYDOLG3DUP1DPH
Description:
There is a bad key in the configuration file.
Parameters:
badKey: the bad key in the configuration file.
filename: the path to the configuration file.
errorLine: the line number at in the configuration file.
Cause:
This indicates that there was 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.
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.
Action(s):
Fix the configuration file manually using a text editor.
&RQI,QYDOLG3URJ1DPH
Description:
There is a bad key in the configuration file.
Parameters:
badKey: the bad key in the configuration file.
filename: the path to the configuration file.
errorLine: the line number at in the configuration file.
Cause:
This indicates that there was 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.
Effect:
The event is of critical severity.
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.
Action(s):
454
Fix the configuration file manually using a text editor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI.H\$GGHG
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.
&RQI.H\'HOHWHG
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.
&RQI/LFHQVH([SLUHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
455
InterMail Kx Reference Guide
&RQI/LFHQVH([SLULQJ6RRQ
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.
&RQI/RFN)DLO
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.
456
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI0LVF(UURU
Description:
An error is occurring while reading the configuration.
Parameters:
None.
Cause:
Corrupt configuration file.
Effect:
The event is of critical severity.
No InterMail application that uses the configuration database runs.
Action(s):
Replace the configuration file with a copy known to be good.
&RQI0LVVLQJ%UDFNHW
Description:
There is no left bracket, which indicates the beginning of the parameter
value.
Parameters:
key: the key in the configuration file.
filename: the path to the configuration file.
errorLine: the line number in the configuration file.
Cause:
Someone is editing the file incorrectly.
Effect:
The event is of critical severity.
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.
Action(s):
Fix the configuration file manually using a text editor.
&RQI0LVVLQJ%UDFNHW
Description:
The same key (parameter name) appears twice in the configuration file.
Parameters:
key: the key in the configuration file.
filename: the path to the configuration file.
errorLine: the line number 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.
Action(s):
Fix the configuration file manually using a text editor.
Confidential and Proprietary, © Software.com, Inc. 1999
457
InterMail Kx Reference Guide
&RQI0LVVLQJ&RORQ
Description:
There is no colon, which terminates a parameter name.
Parameters:
key: the key in the configuration file.
filename: the path to the configuration file.
errorLine: the line number in the configuration file.
Cause:
Someone is incorrectly editing the file.
Effect:
The event is of critical severity.
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.
Action(s):
Fix the configuration file manually using a text editor.
&RQI0LVVLQJ5HTXLUHG3DUDPHWHU
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.
458
Effect:
The event is of serious severity, but depends on the particular parameter.
Action(s):
Put the required parameter back in the config.db.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI0RG1DPH6L]H7RR/DUJH
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.
&RQI0VJ&DW1RW)QG
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 hardcoded 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.
Confidential and Proprietary, © Software.com, Inc. 1999
459
InterMail Kx Reference Guide
&RQI0VJ&DW6WDW)DLO
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 hardcoded 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.
&RQI1HZHU3DUPV5HWXUQHG
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.
460
Cause:
A client connecting to the configuration server.
Effect:
None.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI1R&RQQ7UDFH
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.
&RQI1R'RPDLQ1DPH
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.
&RQI1R+HDGHU
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.
Confidential and Proprietary, © Software.com, Inc. 1999
461
InterMail Kx Reference Guide
&RQI1R8SGDWH
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
&RQI1RQ6WDQGDUG3RUW
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.
462
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI1RW$&RQILJXUHG+RVW
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.
&RQI2WKHU+RVW+DV/RFNHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
463
InterMail Kx Reference Guide
&RQI3DUP&KDQJHG
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.
newTimeStamp: the timestamp of the new 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.
&RQI3DUP(UURU
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.
464
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI3DUPV3XVK
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.
&RQI3RUW&RQIOLFW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
465
InterMail Kx Reference Guide
&RQI3RUW&RQIOLFW5DQJH
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.
&RQI6GE3DWK1DPH$QG)LOH5HTXLUHG
Description:
A path and a filename are required
Parameters:
pathName: the path name.
fileName: the file name.
466
Cause:
None.
Effect:
This event is of critical severity. The application does not run.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
&RQI6HDUFK'LUV$UUD\6L]H
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.
Action(s):
Contact your InterMail vendor.
&RQI6HUYHU/RFN
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.
&RQI6HUYHU1RW&RQILJXUHG)RU+RVW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
467
InterMail Kx Reference Guide
&RQI6HUYHU1RW/RFNHG
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.
&RQI6WDUW8SGDWH
Description:
The operation of assessing the impact of a new set of configuration keys
has begun.
Parameters:
oldTimeStamp: the timestamp of the previous dictionary.
newTimeStamp: the timestamp of the new 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.
&RQI:URQJ1XP'\QDPLF.H\V
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.
468
Cause:
None.
Effect:
The program will not be able to get the correct value for the configuration
key. The results are not predictable.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
Database Log Events
%GE$SS,QLW)DLOHG
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.
%GE%DG'DWD)RUPDW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
469
InterMail Kx Reference Guide
%GE&XUVRU&UHDWH)DLOHG
Description:
Parameters:
An attempt to create a cursor in the file filename failed with error code
code (string).
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
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.
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.
%GE&XUVRU2S)DLOHG
Description:
An attempt to perform a cursor operation operation in the file filename
failed with the error code code (string).
Parameters:
filename: name of the database file.
operation: text representation of the attempted operation.
code: error code given for the failure.
string: text error string associated with the error code.
470
Cause:
An attempt to perform a cursor operation operation 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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
%GE'DWDEDVH1RWH
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.
%GE'DWD,QFRQVLVWHQF\
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.
%GE'HDGORFN'HWHFWHG
Description:
Recoverable deadlock condition was detected (file=%s, op=%s).
Parameters:
filename: name of the database file.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
471
InterMail Kx Reference Guide
%GE'HOHWH)DLOHG
Description:
An attempt to delete a record from the file filename failed with error code
code (string).
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
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.
%GE)LOH2SHQ)DLOHG
Description:
The database file filename could not be opened.
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
472
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
%GE*HW)DLOHG
Description:
An attempt to get a record in the file filename failed with error code code
(string).
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
Cause:
An attempt to get a record in the file filename failed with error code code
(string).
Effect:
A potentially serious denial of service, since database operations cannot
be performed as expected.
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.
%GE,QGH[5HEXLOG)DLOHG
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.
Action(s):
Contact your InterMail vendor.
%GE,QGH[5HEXLOG6XFFHHGHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
473
InterMail Kx Reference Guide
%GE,QLW)DLOHG
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.
%GE0HVVDJH5HFRUG0LVVLQJ
Description:
The message information record for message message was not found.
Parameters:
message: name of the message.
Cause:
A record for a message is missing.
Effect:
The 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.
%GE0VJ,'0LVPDWFK
474
Description:
The message ID for message message is inconsistent with the retrieved
message.
Parameters:
message: name of the 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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
%GE3XW)DLOHG
Description:
An attempt to modify a record in the file filename failed with error code
code (string).
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
Cause:
An attempt to modify a record in the file filename failed with error code
code (string).
Effect:
A potentially serious denial of service, since database operations cannot
be performed as expected.
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.
%GE6WDUW,Q%DFNXS0RGH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
475
InterMail Kx Reference Guide
%GE7[Q$ERUW)DLOHG
Description:
An attempt to commit a transaction for the file filename failed with error
code code (string).
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
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.
%GE7[Q&RPPLW)DLOHG
Description:
An attempt to commit a transaction for the file filename failed with error
code code (string).
Parameters:
filename: name of the database file.
code: error code given for the failure.
string: text error string associated with the error code.
476
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
'E&DFKH&RQQHFW
Description:
Successfully connected to InterMail Directory database.
Parameters:
None.
Cause:
None.
Effect:
The event is of informational severity.
Action(s):
None.
'E&DFKH'LVFRQQHFW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
477
InterMail Kx Reference Guide
'E'DWDEDVH(UURU
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.
478
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
'E,QLW1R3DWK
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.
'E0HVVDJH)LOHV'LU1RW6SHFLILHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
479
InterMail Kx Reference Guide
'E0VJ,'0LVPDWFK
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.
480
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
'E1DPH7RR/RQJ
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.
Action(s):
Contact your InterMail vendor.
'E1R0HVVDJH)LOH6WRUDJH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
481
InterMail Kx Reference Guide
'E1XP&OLHQW&RQQHFWLRQV
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.
Action(s):
Contact your InterMail vendor.
'E7RR0DQ\'LU&OLHQW3RRO
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.
Action(s):
Contact your InterMail vendor.
'E9DOXH7RR/RQJ
Description:
The value specified for a mailbox property was longer than the maximum
length supported by this MSS schema.
Parameters:
None.
Cause:
482
Effect:
The event is of error severity. The current database operation will fail.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
Directory Cache Log Events
&DFKH8SGDWH7LPH7RR/RQJ
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.
Filter Log Events
)LOW$FWLRQ%RXQFH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
483
InterMail Kx Reference Guide
)LOW$FWLRQ%RXQFH7ZLFH
Description:
A mail filter executed the “bounce” action twice, which the system does
not allow. The system will honor only the first “bounce” action.
Parameters:
filterName: the name of the filter executing.
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.
)LOW$FWLRQ&RQIOLFW
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”.
Parameters:
filterName: the name of the filter executing.
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.
)LOW$FWLRQ)RUZDUG
Description:
A mail filter has processed a message and forwarded it to another address
(using the “forward” action).
Parameters:
filterName: the name of the filter executing.
address: the forwardee’s address.
484
Cause:
The filter used the “forward” action.
Effect:
This message is for informational purposes only.
Action(s):
None required.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LOW$FWLRQ5HMHFW
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.
Parameters:
filterName: the name of the filter executing.
message: the rejection message.
Cause:
The filter used the “reject” action.
Effect:
This message is for informational purposes only.
Action(s):
None required.
)LOW$FWLRQ5HMHFW7ZLFH
Description:
A mail filter executed the “reject” action twice, which the system does
not allow. The system will honor only the first “reject” action.
Parameters:
filterName: the name of the filter executing.
Cause:
The mail filter may have a bug that is causing the multiple rejects.
Effect:
This message is of warning severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
485
InterMail Kx Reference Guide
)LOW$FWLRQ6LGHOLQH
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.
Parameters:
filterName: the name of the filter executing.
dir: the sideline directory.
Cause:
The filter used the “sideline” action.
Effect:
This message is for informational purposes only.
Action(s):
None required.
)LOW$FWLRQ6LGHOLQH7ZLFH
Description:
A mail filter executed the “sideline” action twice, which the system does
not allow. It will only use the first “sideline” action.
Parameters:
filterName: the name of the filter executing.
Cause:
The mail filter may have a bug that is causing the multiple sidelines.
Effect:
This message is of warning severity.
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.
)LOW$FWLRQ7RVV
486
Description:
A mail filter has processed a message and caused it to drop (using the
“toss” action).
Parameters:
filterName: the name of the filter executing.
Cause:
The filter used the “toss” action.
Effect:
This message is for informational purposes only.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LOW3DUVH)DLO
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.
File Input/Output Log Events
)LR%ORFN2Q3LSH
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.
Effect:
The event is of warning severity.
Action(s):
None, unless you do not want blocking; in which case, change the
configuration key logNamedPipeMode.
Confidential and Proprietary, © Software.com, Inc. 1999
487
InterMail Kx Reference Guide
)LR&ORVH)DLO
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.
Effect:
The event is of critical severity.
Action(s):
Determine what caused this event.
)LR&RS\)LOH)DLO
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.
488
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR&UHDWH)DLO
Description:
The creation of the file filename failed with system error
systemErrString.
Parameters:
filename: the name of the file.
systemErrString: the system error string.
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.
)LR&UHDWH3RUW)LOH)DLO
Description:
The system call to open with filename filename failed with system error
systemErrString.
Parameters:
filename: the name of the file.
systemErrString: the system error string.
Cause:
• The file already exists.
• The listener process does not have adequate permissions to create the
file.
• The system file table is full.
Effect:
The event is of major severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
489
InterMail Kx Reference Guide
)LR'LU0LVVLQJ
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.
systemErrString: the system error string.
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.
Effect:
The event is of major severity.
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.
)LR)FQWO)DLO
Description:
The call to fcntl() on file filename failed with error systemErrString.
Specifically, there was a problem making the named pipe have nonblocking I/O.
Parameters:
filename: the name of the file.
systemErrString: the system error string.
490
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR)V\QF)DLO
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.
systemErrString: the system error string.
Cause:
• System moved or removed file before the fsync call.
• A signal caught during the fsync call
Effect:
The event is of minor severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
491
InterMail Kx Reference Guide
)LR/LQN)DLO
Description:
Parameters:
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.
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):
492
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR0DNH'LU)DLO
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.
systemErrString: the system error string.
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.
)LR0NQRG)DLO
Description:
An attempt to create a named pipe has failed. A system call to mknod did
this.
Parameters:
namedPipe: the name of the pipe.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
493
InterMail Kx Reference Guide
)LR0PDS)DLOHG
Description:
An attempt to memory-map a file failed.
Parameters:
filename: the file name.
systemErrorString: the system error string.
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.
)LR0PDS)LOH1RW2SHQ
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.
Action(s):
Contact your InterMail vendor.
)LR1R5HDGHUV
Description:
Named pipe %s has no readers.
Parameters:
namedPipePath: the full path of the named pipe.
Cause:
Effect:
Action(s):
494
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR2SHQ'LU)DLO
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.
systemErrString: the system error string.
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.
)LR2SHQ)DLO
Description:
The call to open with file filename failed with system error
systemErrorString. The opContext provides the context of the open call.
Parameters:
filename: the name of the file.
opContext: text explanation of attempted operation.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
495
InterMail Kx Reference Guide
)LR3LSH+QGOU
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:
Action(s):
Contact your InterMail vendor.
)LR3LSH2SHQ)DLO
Description:
An attempt to open a named pipe for writing failed. This happens when
creating the logfile.
Parameters:
namedPipePath: the full path to the named pipe.
systemErrorString: the system error string.
496
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().
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR3LSH:ULWH
Description:
An attempt to write to a named pipe failed. This happens when writing to
a logfile.
Parameters:
namedPipePath: the full path to the named pipe.
systemErrorString: the system error string.
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.
)LR3LSH:UW)DLO
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.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
497
InterMail Kx Reference Guide
)LR3UHPDWXUH(2)
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.
)LR5HDG)DLO
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.
498
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR5HQDPH)LOH)DLO
Description:
Renaming file oldFilename to newFilename failed with system error
systemErrorString.
Parameters:
oldFilename: the old filename.
newFilename: the new filename.
systemErrorString: the system error string.
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.
)LR5PGLU)DLO
Description:
The system call to rmdir with filename dir failed with system error
systemErrorString.
Parameters:
dir: the name of the directory.
systemErrorString: the system error string.
Cause:
• The server performing the rmdir does not have adequate
permissions.
• The name of the file is too long.
Effect:
The event is of minor severity.
Action(s):
Determine the cause responsible for this event. Expected directories may
be missing.
Confidential and Proprietary, © Software.com, Inc. 1999
499
InterMail Kx Reference Guide
)LR6HHN)DLO
Description:
Performing an lseek results in the error systemErrorString.
Parameters:
systemErrorString: the system error string.
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.
)LR6WDW)DLO
Description:
The {l,f,}stat command failed on file filename with
systemErrorString. The context is either in the MSS or the Directory
server.
Parameters:
filename: the filename.
systemErrorString: the system error string.
Cause:
• The server does not have adequate permissions.
• The file does not exist.
• A signal caught during the stat call.
• The length of the filename is too long.
500
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
)LR6WDWYIV)DLO
Description:
Parameters:
The statvfs command failed on file filename with systemErrorString.
Currently, the only context where this message occurs is in the MSS.
Matches FIOStatvfsErr.
filename: the filename.
systemErrorString: the system error string.
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.
)LR8QOLQN)DLO
Description:
The system call to unlink with file filename failed with system error
systemErrorString.
Parameters:
filename: the name of the file.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
501
InterMail Kx Reference Guide
)LR:ULWH)DLO
Description:
The call to write with file filename failed with system error
systemErrorString. The opContext provides the context of the write.
Parameters:
filename: the name of the file.
Filename: text explanation of attempted operation.
systemErrorString: the system error string.
Cause:
• The server performing the write does not have adequate permissions.
• The file does not exist.
• 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.
IMAP Log Events
,PDS%DG0VJ1XP
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):
502
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
,PDS&RPPDQG)DLOHG
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.
,PDS&RPPDQG)DLOHG5HDVRQ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
503
InterMail Kx Reference Guide
,PDS&RQQ%URNHQ
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.
,PDS&RQQ0DGH
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.
,PDS&RQQ7LPHG2XW
504
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.
Effect:
This is a notification.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
,PDS'LVFRQQHFWHG
Description:
Connection with the IMAP client has terminated.
Parameters:
None.
Cause:
The user’s connection has terminated.
Effect:
This is a notification.
Action(s):
None.
,PDS066(UURU
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.
,PDS0D[6HVVLRQV
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.
Confidential and Proprietary, © Software.com, Inc. 1999
505
InterMail Kx Reference Guide
,PDS1R3UR[\/RJLQ
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.
,PDS3URWRFRO(UU
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.
,PDS6\QF(UURU
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):
506
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
,PDS8,'2XW2I2UGHU
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.
.H\ZRUG7RR/RQJ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
507
InterMail Kx Reference Guide
LDAP Log Events
VWULQJ!OLQHLQWHJHU!EDGFRQILJOLQHLJQRUHG
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.
VWULQJ!OLQHLQWHJHU!PLVVLQJGQLQUHSORJILOH
ILOHQDPH!OLQH
Description:
The replogfile directive is missing a distinguished name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJGQLQURRWGQGQ!OLQH
Description:
The rootdn directive is missing a distinguished name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
508
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
VWULQJ!OLQHLQWHJHU!PLVVLQJGQLQVXIIL[GQ!OLQH
Description:
The updatedn directive is missing a distinguished name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJGQLQXSGDWHGQGQ!
OLQH
Description:
The suffix directive is missing a distinguished name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJILOHQDPHLQLQFOXGH
ILOHQDPH!OLQH
Description:
An include directive is missing the expected filename.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
509
InterMail Kx Reference Guide
VWULQJ!OLQHLQWHJHU!PLVVLQJILOHQDPHLQVUYWDE
ILOHQDPH!OLQH
Description:
A srvtab directive is missing the expected filename.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJKRVWLQUHSOLFD
KRVW>SRUW@!OLQH
Description:
The replica directive is missing the host name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJKRVWLQUHSOLFDOLQH
LJQRUHG
Description:
The replica directive is missing a host name.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
510
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
VWULQJ!OLQHLQWHJHU!PLVVLQJOLPLWLQVL]HOLPLWOLPLW!
OLQH
Description:
The sizelimit directive in the configuration file is missing the actual
limit.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJOLPLWLQWLPHOLPLWOLPLW!
OLQH
Description:
The timeline directive in the configuration file is missing the actual
limit.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
511
InterMail Kx Reference Guide
VWULQJ!OLQHLQWHJHU!PLVVLQJQDPHLQDWWULEXWH
QDPH!V\QWD[!
Description:
Attribute decoding is missing a name.
Parameters:
<string> = name of the input file.
<integer> = line number in the file where there is an error.
Cause:
Attribute is missing name as shown.
Effect:
The attribute is ignored.
Action(s):
Find and fix the attribute at the source.
VWULQJ!OLQHLQWHJHU!PLVVLQJRQ_RIILQODVWPRG
RQ_RII!OLQH
Description:
The lastmod directive is missing the on/off parameter.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
512
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
VWULQJ!OLQHLQWHJHU!PLVVLQJRQ_RIILQUHDGRQO\
RQ_RII!OLQH
Description:
The readonly directive is missing the on/off parameter.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJSDVVZGLQURRWSZ
SDVVZG!OLQH
Description:
The rootpw directive is missing a password.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!PLVVLQJW\SHLQGDWDEDVHW\SH!
OLQH
Description:
The configuration line that specifies the database type, is missing the
type.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the configuration line for database type to read correctly.
Confidential and Proprietary, © Software.com, Inc. 1999
513
InterMail Kx Reference Guide
VWULQJ!OLQHLQWHJHU!PLVVLQJ85/LQUHIHUUDO85/!
OLQH
Description:
The referenceURL directive is missing the URL.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!UHDGRQO\OLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
The readonly directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!UHSOLFDOLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
The replica directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
514
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
VWULQJ!OLQHLQWHJHU!URRWGQOLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
The rootdn directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!URRWSZOLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
The rootpw directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!VXIIL[OLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
A suffix directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
515
InterMail Kx Reference Guide
VWULQJ!OLQHLQWHJHU!XQNQRZQGLUHFWLYHVWULQJ!
RXWVLGHGDWDEDVHGHILQLWLRQLJQRUHG
Description:
A directive given outside a database definition is not recognized.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!XSGDWHGQOLQHPXVWDSSHDULQVLGHD
GDWDEDVHGHILQLWLRQLJQRUHG
Description:
The updatedn directive must appear inside a database definition.
Parameters:
<string> = name of the configuration file.
<integer> = line number in the file where there is an error.
516
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
VWULQJ!OLQHLQWHJHU!H[WUDFUXIWDIWHUGQ!LQVXIIL[
VWULQJ!OLQHLJQRUHG
Description:
The distinguished name in the suffix directive is followed by
unnecessary text.
Parameters:
<string1> = name of the configuration file.
<integer> = line number in the file where there is an error.
<string2> = unnecessary text.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
VWULQJ!OLQHLQWHJHU!XQNQRZQGLUHFWLYHVWULQJ!
LQVLGHGDWDEDVHGHILQLWLRQLJQRUHG
Description:
A directive given inside a database definition is not recognized.
Parameters:
<string1> = name of the configuration file.
<integer> = line number in the file where there is an error.
<string2> = unrecognized directive.
Cause:
See description.
Effect:
The directive is ignored.
Action(s):
Fix the directive in the configuration file.
Confidential and Proprietary, © Software.com, Inc. 1999
517
InterMail Kx Reference Guide
VWULQJ!OLQHLQWHJHU!XQNQRZQV\QWD[VWULQJ!LQ
DWWULEXWHOLQHLJQRUHG
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.
Effect:
The attribute is ignored.
Action(s):
Find and fix the attribute at the source.
EHUBDOORFIDLOHGLQFRQQHFWLRQ
518
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
EHUBDOORFIDLOHGLQUHVXOW
Description:
Basic Encoding Rules decoding is failing to allocate resources.
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.
EHUBDOORFIDLOHGLQUHVXOW
Description:
Basic Encoding Rules decoding is failing to allocate resources.
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.
EHUBJHWBLQWUHWXUQV[KH[!
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.
Confidential and Proprietary, © Software.com, Inc. 1999
519
InterMail Kx Reference Guide
EHUBSHHNBWDJUHWXUQV[KH[!
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.
EHUBSULQWIIDLOHGLQVHQGB,GDSBUHVXOW
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.
EHUBSULQWIIDLOHGLQVHQGBVHDUFKBHQWU\
520
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
EHUBSULQWIIDLOHGLQVHQGBVHDUFKBHQWU\
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.
EHUBSULQWIIDLOHGLQVHQGBVHDUFKBHQWU\
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.
EHUBSULQWIIDLOHGLQVHQGBVHDUFKBHQWU\
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.
Confidential and Proprietary, © Software.com, Inc. 1999
521
InterMail Kx Reference Guide
EHUBSULQWIIDLOHGLQVHQGBVHDUFKBHQWU\
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.
EHUBVFDQIIDLOHGLQDEDQGRQ
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
EHUBVFDQIIDLOHGLQDGG
522
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
EHUBVFDQIIDLOHGLQELQG
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
EHUBVFDQIIDLOHGLQFRPSDUH
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
EHUBVFDQIIDLOHGLQGHOHWH
Description:
Basic Encoding Rules decoding is failing on the input data.
Parameters:
None.
Cause:
Request to delete is malforming BER encoding.
Effect:
LDAP Protocol Error is returned to client.
Action(s):
Fix the client that is sending incorrectly formatted data.
Confidential and Proprietary, © Software.com, Inc. 1999
523
InterMail Kx Reference Guide
EHUBVFDQIIDLOHGLQPRGLI\
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
EHUBVFDQIIDLOHGLQPRGUGQ
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
FDOORFRILQWHJHU!HOHPVRILQWHJHU!E\WHVIDLOHG
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.
524
Cause:
Request for memory is failing, possibly the machine is out of swap.
Effect:
The server exits.
Action(s):
Find out what is using up memory, or if normal operations, get more
memory or increase swap on the machine.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
FRXOGQRWRSHQORFNILOHVWULQJ!
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.
FRXOGQRWRSHQORJILOHVWULQJ!
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.
FRXOGQRWRSHQFRQILJILOHVWULQJ!DEVROXWHSDWK"
Description:
The configuration file cannot open.
Parameters:
<string> = name of the configuration file.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
525
InterMail Kx Reference Guide
GQBQRUPDOL]HXQNQRZQVWDWHLQWHJHU!
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.
(QWU\VWULQJ!DWWUVWULQJ!QRWDOORZHG
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.
(QWU\VWULQJ!UHTXLUHGDWWUVWULQJ!PLVVLQJ
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.
526
Cause:
Provided entry does not match the schema.
Effect:
The entry cannot be processed.
Action(s):
Fix the schema, or correct the data.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
JHWBDYDEHUBVFDQI
Description:
Basic Encoding Rules decoding is failing on the input data.
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.
PDOORFRILQWHJHU!E\WHVIDLOHG
Description:
The LDAP server is unable to allocate memory.
Parameters:
<integer> = number of bytes attempted to allocate.
Cause:
Request for memory is failing, possibly the machine is out of swap.
Effect:
The server exits.
Action(s):
Find out what is using up memory, or if normal operations, get more
memory or increase swap on the machine.
1RREMHFWFODVVIRUHQWU\VWULQJ!
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.
Cause:
Provided entry does not match the schema.
Effect:
The entry cannot be processed.
Action(s):
Fix the schema, or correct the data.
Confidential and Proprietary, © Software.com, Inc. 1999
527
InterMail Kx Reference Guide
QRYDOXHVIRUW\SHVWULQJ!
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.
RSBGHOHWHFDQ
WILQGRSLQWHJHU!
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.
SRVVLEOHV\QWD[HVDUHFLVFHVWHOGQRUELQ
528
Description:
Attribute syntax is unknown.
Parameters:
None.
Cause:
Syntax error in attribute line shown.
Effect:
The attribute is ignored.
Action(s):
Find and fix the attribute at the source.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
UHDOORFRILQWHJHU!E\WHVIDLOHG
Description:
The LDAP server is unable to allocate memory.
Parameters:
<integer> = number of bytes attempted to allocate.
Cause:
Request for memory is failing, possibly the machine is out of swap.
Effect:
The server exits.
Action(s):
Find out what is using up memory, or if normal operations, get more
memory or increase swap on the machine.
VWUHQWU\HQWU\LQWHJHU!KDVPXOWLSOHGQVVWULQJ!DQG
VWULQJ!VHFRQGLJQRUHG
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).
Cause:
See description.
Effect:
See description.
Action(s):
None required.
VWUHQWU\HQWU\LQWHJHU!KDVQRGQ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
529
InterMail Kx Reference Guide
VWUUHVXOWVWULQJ!H[SHFWLQJ5(68/7
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.
Cause:
Internal server error.
Effect:
The encoding of the result stops.
Action(s):
None possible.
VWUUHVXOWVWULQJ!XQNQRZQ
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.
Cause:
Internal server error.
Effect:
The encoding of the result stops.
Action(s):
None possible.
VWUGXSRIVWULQJ!
530
Description:
The LDAP server is unable to allocate memory.
Parameters:
<string> = string that is attempting to be duplicated.
Cause:
Request for memory is failing, possibly the machine is out of swap.
Effect:
Server exits.
Action(s):
Find out what is using up memory, or if normal operations, get more
memory or increase swap on the machine.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
7RRPDQ\WRNHQVPD[LQWHJHU!
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.
Effect:
The server exits.
Action(s):
Fix the directive in the configuration file.
XQNQRZQILOWHUW\SHLQWHJHU!LQJHWBILOWHU
Description:
A filter is specified with an unknown type.
Parameters:
<integer> = type number of the filter at fault.
Cause:
See description.
Effect:
An LDAP Protocol Error is signaled.
Action(s):
Fix the filter specification.
XQNQRZQILOWHUW\SHLQWHJHU!LQILOWHUBIUHH
Description:
When freeing a filter, the type is not recognized.
Parameters:
<integer> = type number of the filter at fault.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
531
InterMail Kx Reference Guide
XQNQRZQILOWHUW\SHLQWHJHU!LQWHVWBILOWHU
Description:
A filter that is running against a query does not have a recognized type.
Parameters:
<integer> = type number of the filter at fault.
Cause:
Invalid filter specified.
Effect:
The filter is skipped, no match is found.
Action(s):
Determine the filter at fault and eliminate.
XQNQRZQYHUVLRQLQWHJHU!
Description:
The version in the bind request is not recognized.
Parameters:
<integer> = unrecognized version.
Cause:
See description.
Effect:
Server returns Protocol Error, declines bind from client.
Action(s):
Fix the client to use a compatible protocol to the server.
YHUVLRQGHWHFWHG
532
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.
Action(s):
None required.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
Message Store Log Events
0V$OUHDG\([LVWV
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.
0V$OUHDG\3RS/RFNHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
533
InterMail Kx Reference Guide
0V%DG%RXQFH1RWLFH3DUP
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.
Action(s):
Contact your InterMail vendor.
0V%DG'EQDPH
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.
0V%DG06
534
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V%DG0VV6WDWLVWLF
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.
Action(s):
Contact your InterMail vendor.
0V%DG4XHU\
Description:
The message store server received a query with an invalid type.
Parameters:
None.
Cause:
Effect:
The event is of minor severity. Affects a single message store only.
Action(s):
Contact your InterMail vendor.
0V%DG6WDWLVWLF
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.
Effect:
The event is of minor severity. Affects a single message store only.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
535
InterMail Kx Reference Guide
0V%DG85/
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.
0V%URDGFDVW)DLO
Description:
The message broadcast failed because message store msName among
numberms was not available for more than two hours.
Parameters:
msName: the name of the message store.
numberms: the number of message store.
536
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V%XFNHW3DWK7RR/RQJ
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.
Effect:
The event is of minor severity.
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.
0V&RUUXSW6WRUHV'LFW
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.
Parameters:
msName: the name of the 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.
Confidential and Proprietary, © Software.com, Inc. 1999
537
InterMail Kx Reference Guide
0V'HOHWH06)DLO
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.
0V'HOLYHU)ROGHU1RW)RXQG
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.
0V'XSOLFDWH1DPH
538
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.
Effect:
The event is of warning severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V(PSW\
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.
0V(PSW\%XFNHWV)LOH
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.
• Some damage is occurring to the message data area file system.
• 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.
Confidential and Proprietary, © Software.com, Inc. 1999
539
InterMail Kx Reference Guide
0V(PSW\)ROGHU1RW6XSS
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.
0V(PSW\061DPH
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.
0V)ROGHU/RRS
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.
540
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V)ROGHU1RW,Q)ROGHU
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.
Effect:
This message is of informational severity. Affects a single message store
only.
Action(s):
None. This is a user error.
0V)ROGHU1RW0RYDEOH
Description:
A client of the message store server attempted to move folder
folderName, which is not movable. This folder is probably the trash
folder.
Parameters:
folderName: the name of the folder.
Cause:
An attempt to move either the trash folder or any other folder by a client
of the message store server.
Effect:
This message is of informational severity. Affects a single message store
only.
Action(s):
None. This is a user error.
Confidential and Proprietary, © Software.com, Inc. 1999
541
InterMail Kx Reference Guide
0V)ROGHU1RW5HPRYDEOH
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.
Effect:
The event is of informational severity.
Action(s):
This is a user error.
0V)ROGHU1RW5HQDPDEOH
542
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.
Parameters:
folderName: the name of the folder.
Cause:
An attempt to rename either the trash folder or any other folder by a client
of the message store server.
Effect:
This message is of informational severity. Affects a single message store
only.
Action(s):
None. This is a user error.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V)XOO%XFNHW
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.
• Some damage is occurring to the message data area file system.
• 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.
0V,QLW)DLOXUH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
543
InterMail Kx Reference Guide
0V,QYDOLG0VJ)ODJ
Description:
The message store server received a query for invalid message flags.
Parameters:
None.
Cause:
Effect:
The event is of minor severity. Affects a single message store only.
Action(s):
If the error repeats frequently, contact your InterMail vendor.
0V,QYDOLG2EM5HI
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.
0V.H\ZRUG7RR/RQJ
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
544
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V/LPLW0VJ6L]H
Description:
Parameters:
The size of the message msgSize exceeded the maximum allowed per
message for message store msName. It will not create the message.
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.
0V/LPLW1XP0VJV
Description:
The number of messages in message store msName is at limit
maxNumMsgs. It did not create the new message.
Parameters:
msName: the message store name.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
545
InterMail Kx Reference Guide
0V/LPLW7RWDO6L]H
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.
Parameters:
msName: the message store name.
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.
0V/RDGHG%\2WKHU066
546
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.
Effect:
This message is of informational severity.
Action(s):
None. This is expected behavior.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V0DLOER[&UHDWHG
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.
Effect:
This message is of informational severity.
Action(s):
None. This is expected behavior.
0V0LVVLQJ'EQDPH
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.
0V0LVVLQJ2EMHFW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
547
InterMail Kx Reference Guide
0V0VJ%DG)RUPDW
Description:
Parameters:
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.
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):
0V0VJ&UHDWHG
Description:
A message with message id msgId added to message store msName.
Parameters:
msgId: the message id.
msName: the name of the message store.
Cause:
This is not an exception or error. It is strictly a notification.
Effect:
This message is of informational severity.
Action(s):
0V0VJ'HOHWHG
Description:
A message with message id msgId deleted from message store msName.
Parameters:
msgId: the message id.
msName: the name of the message store.
548
Cause:
This is not an exception or error. It is strictly a notification.
Effect:
This message is of informational severity.
Action(s):
None. This is expected behavior.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V0VJ,'1RW)RXQG
Description:
A client of the message store server attempted to retrieve a message with
message id msgId. This ID not found.
Parameters:
msgId: the message id.
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.
0V0VJ/RFNHG
Description:
Message msgId currently locked.
Parameters:
msgId: the message id.
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.
0V0VJ1RW,Q)ROGHU
Description:
The message msgId is no longer in folder folderName.
Parameters:
msgId: the message id.
folderName: the name of the folder.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
549
InterMail Kx Reference Guide
0V0VJ1RW/RFNHG
Description:
The message msgId to unlock is not locked. (This functionality is
becoming obsolete.)
Parameters:
msgId: the message id.
Cause:
Message already unlocked. Operation probably repeated.
Effect:
The event is of informational severity. Affects a single message store
only.
Action(s):
None.
0V0VJ5DQJH5HDG
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.
msName: the name of the message store.
folderName: the name of the folder.
userName: the name of the user who read the message.
550
Cause:
Expected behavior.
Effect:
None. The event is of informational severity.
Action(s):
None, this is a notification of expected behavior.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V0VJ5HDG
Description:
Read a message with message id msgId in message store msName in
folder folderName by user userName.
Parameters:
msgId: the message id.
msName: the name of the message store.
folderName: the name of the folder.
userName: the name of the user who read the message.
Cause:
This is expected behavior.
Effect:
This message is of informational severity.
Action(s):
None. This is expected behavior.
0V1R$OORZ'HOLYHU
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.
Confidential and Proprietary, © Software.com, Inc. 1999
551
InterMail Kx Reference Guide
0V1R5LJKW
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.
0V1R8QORFNHG0VJV
Description:
All messages in folder folderName currently locked. (This functionality
is becoming obsolete.)
Parameters:
folderName: the name of the folder.
Cause:
User error.
Effect:
The event is of minor severity. It affects a single message store only.
Action(s):
None.
0V1R:HOFRPH0VJ
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.
552
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V1RW$)ROGHU5HI
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.
Action(s):
Contact your InterMail vendor.
0V1RW$0VJ5HI
Description:
The message msgId already deleted.
Parameters:
msgId: the message id.
Cause:
Message in a search folder already deleted.
Effect:
The event is of warning severity. It affects a single message store only.
Action(s):
Contact your InterMail vendor.
0V1RW$6HDUFK5HI
Description:
The search container searchContainer already deleted.
Parameters:
searchContainer: the search container.
Cause:
Search folder already deleted.
Effect:
The event is of warning severity. It affects a single message store only.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
553
InterMail Kx Reference Guide
0V1RW)RXQG
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.
0V1XOO)ROGHU1DPH
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.
Effect:
The event is of minor severity. It affects a single message store only.
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.
0V2EMHFW/RFNHG
Description:
User userName on machine host is currently viewing a message or folder
while another client was attempting to move, remove, or replace it.
Parameters:
userName: the name of the user.
host: the name of the machine the user is on.
554
Cause:
Multiple clients are viewing a message store.
Effect:
The event is of minor severity. It affects a single message store only.
Action(s):
Client should try the action again later. If error continually repeats, reboot
InterMail servers.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V2EMHFW/RFNHG%\6HUYHU
Description:
The message store server temporarily locks a message or folder.
Parameters:
None.
Cause:
The MSS is performing an action for another client.
Effect:
The event is of minor severity. It affects a single message store only.
Action(s):
Client should try the action again later. If the error continually repeats,
reboot the MSS process.
0V2S1RW6XSSRUWHG
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.
Action(s):
Contact your InterMail vendor.
0V3URSHUW\1RW6XSSRUWHG
Description:
An invalid property type requested of the message store.
Parameters:
msName: the message store name.
Cause:
An administration property designed for non-database message stores
accessed on a database message store.
Effect:
The event is of minor severity. It affects a single message store only.
Action(s):
• Check revisions of InterMail software.
• Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
555
InterMail Kx Reference Guide
0V5HVWULFWHG7R5RRW
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.
Parameters:
folderName: the name of the folder.
Cause:
An client attempted to create an invalid InBox folder.
Effect:
The event is of minor severity. Affects a single message store only.
Action(s):
Contact your InterMail vendor.
0V6HDUFK2S1RW6XSSRUWHG
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.
Effect:
The event is of minor severity. Affects a single message store only.
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.
0V8QNQRZQ2EM7\SH
Description:
An internal id refers to an object of an unknown type.
Parameters:
None.
Cause:
556
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0V8QNQRZQ3URSHUW\
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:
Effect:
The event is of minor severity. It affects a single message store only.
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.
0V8QVXSSRUWHG4XHU\
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.
Effect:
The event is of minor severity.
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.
0V:URQJ06
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.
Confidential and Proprietary, © Software.com, Inc. 1999
557
InterMail Kx Reference Guide
0V:URQJ2EMHFW7\SH
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.
Message (Mail) Log Events
0VJ$WWU*)6
Description:
Attribute::getFromSrc() function called.
Parameters:
None.
Cause:
A class derived from the Attribute class without implementing a
getFromSrc() member function.
558
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ%DG&RQWHQW/HQJWK
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 remigrate, if the problem was due to a correctable file system error.
0VJ%DG(QFO(QFRGH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
559
InterMail Kx Reference Guide
0VJ%DG+HDGHU$WWU
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.
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.
0VJ%DG+H[2LG
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.
Effect:
The event is of minor severity.
Action(s):
Contact your InterMail vendor.
0VJ&ORVH(QFO)DLO
Description:
Could not write an enclosure while writing a message to disk.
Parameters:
pathName: the pathname to the tmp file.
systemErrString: the system error string.
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.
560
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ&UHDWH(QFO)DLO
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).
systemErrString: the system error string.
Cause:
This is probably a file system or hardware error.
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.
• Check ownership and permissions of the tmp directory.
0VJ(QFO%DG&KDU6HT
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
561
InterMail Kx Reference Guide
0VJ(QFO*)6
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.
0VJ(QFO5HDG2QO\
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.
0VJ,PS&RQQ/RVW
562
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ,PS1RWD0VJ
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.
Action(s):
Contact your InterMail vendor.
0VJ,PS2SHQ'LU
Description:
An attempt to import a file has failed.
Parameters:
None.
Cause:
This is probably a file system or hardware error.
Effect:
None.
Action(s):
Contact your InterMail vendor
0VJ,PS2SHQ)DLO
Description:
An attempt to open a file for importing failed.
Parameters:
None.
Cause:
This is probably a file system or hardware error.
Effect:
None.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
563
InterMail Kx Reference Guide
0VJ,PS5HPRWH(UU
Description:
Could not import the file because the message store server reported an
error.
Parameters:
None.
Cause:
This is probably a file system or hardware error.
Effect:
None.
Action(s):
Contact your InterMail vendor.
0VJ,PS6WDW)DLO
Description:
An attempt to stat a file to import failed
Parameters:
None.
Cause:
This is probably a file system or hardware error.
Effect:
None.
Action(s):
Contact your InterMail vendor.
0VJ036,
Description:
MultiPart::swapIn() called.
Parameters:
None.
Cause:
564
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ0362
Description:
MultiPart::swapOut()called.
Parameters:
None.
Cause:
Effect:
The event is of major severity. Affects all users of the concerned server.
Action(s):
Contact your InterMail vendor.
0VJ0RYH)DLO
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.
0VJ0RYH6XFFHVV
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.
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
565
InterMail Kx Reference Guide
0VJ0XOWL3DUW1R%RXQGDU\
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.
0VJ1XOO0VJ
Description:
There was an empty file instead of an Internet message.
Parameters:
None.
Cause:
This is probably a file system or hardware error.
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.
0VJ2LG7RR/RQJ
566
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ2SHQ(QFO)DLO
Description:
Could not open an enclosure of a message.
Parameters:
enclosureFilename: the pathname to the tmp file.
function: open(2).
systemErrString: the system error string.
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 occurs 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 ownership and permissions of the tmp directory
• Check to see that the file system has not run out of space.
0VJ3DUWLDO1R,G
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
567
InterMail Kx Reference Guide
0VJ3UHPDWXUH(QG2I)LOH
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 QuotedPrintable 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.
0VJ5HDG(QFO)DLO
Description:
Doing a read on the enclosure file resulted in a system error.
Parameters:
enclosureFilename: the pathname to the tmp file.
systemErrString: the system error string.
Cause:
This is probably a file system or hardware 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.
Action(s):
• Check system error status reported.
• Check ownership and permissions of the tmp directory.
• Check to see that the file system has not run out of space.
568
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0VJ6HHN(QFO)DLO
Description:
Could not seek an enclosure of a message.
Parameters:
enclosureFilename: the pathname to the tmp file.
function: lseek(2).
systemErrString: the system error string.
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 existence, ownership, and permission of the file named.
• Check to see that the file system has not run out of space.
0VJ6WDW(QFO)DLO
Description:
The stat system call returned an error on the enclosure file.
Parameters:
enclosureFilename: the pathname to the tmp file.
systemErrString: the system error string.
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 existence, ownership, and permission of the file named.
• Check to see that the file system has not run out of space.
Confidential and Proprietary, © Software.com, Inc. 1999
569
InterMail Kx Reference Guide
0VJ7UDFH
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.
0VJ:ULWH7R,QHW&DOOHG
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.
MTA Log Events
0WD$XWK)DLO%DG3VZG
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.
Effect:
The event is of informational severity.
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):
570
Verify the user mail account information including password.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD$XWK)DLO%DG8VHU
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user's account information is correct.
0WD$XWR5HSO\6XSSUHVVHG$OUHDG\6HQW
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.
Effect:
The event is of informational severity.
Action(s):
None.
0WD$XWR5HSO\6XSSUHVVHG1RW,Q+HDGHU
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.
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
571
InterMail Kx Reference Guide
0WD$XWR5HSO\6XSSUHVVHG6HQGHU
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.
Effect:
The event is of informational severity.
Action(s):
None.
07$%DG&RQWURO)LOH
572
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD%RG\)LOH0RYH)DLOHG
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.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of major severity.
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.
0WD%RG\)LOH5HDG)DLOHG
Description:
The MTA was unable to read a message body file.
Parameters:
msgBodyFilename: the name of the message body file.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
573
InterMail Kx Reference Guide
0WD%RG\)LOH:ULWH)DLOHG
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.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of major severity.
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.
0WD&RQWURO)LOH%DG9DOXH
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.
574
Effect:
The event is of minor severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD&RQWURO)LOH0RYH)DLOHG
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.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of major severity.
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.
0WD&RQWURO)LOH5HDG)DLOHG
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.
Effect:
The event is of minor severity.
Action(s):
Check the permissions on the file to ensure that the MTA is able to read
it.
0WD&RQWURO)LOH:ULWH)DLOHG
Description:
The MTA could not write a new copy of the control file for a message.
Parameters:
controlFileName: the name of the control file.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of critical severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
575
InterMail Kx Reference Guide
07$'HIHU'LU5HDG)DLO
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.
systemErrorString: the system error string.
Cause:
Effect:
This is most likely due to permission problems, but the actual reason is
listed in the systemErrorString.
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.
07$'HIHUUHG)LOH0RYH)DLO
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.
576
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
07$'LU&DFKH'RZQ
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.
0WD'RPDLQ7DEOH/RDG)DLOHG
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.
0WD'RPDLQ7DEOH1RW/RDGHG
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).
Confidential and Proprietary, © Software.com, Inc. 1999
577
InterMail Kx Reference Guide
0WD'RPDLQ7DEOH8SGDWH)DLOHG
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.
0WD(UURU7UDFH
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.
578
Cause:
The error in the control file should indicate the reason the system could
not return the message to its sender.
Effect:
The event is of warning severity.
Action(s):
Check the control file to see why system could not return it.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD+HDGHU)LOH0RYH)DLOHG
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.
systemErrString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of major severity.
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.
0WD+HDGHU)LOH5HDG)DLOHG
Description:
The MTA was unable to read a message header file.
Parameters:
msgHeaderFilename: the name of the message header file.
sysErrorString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
579
InterMail Kx Reference Guide
0WD+HDGHU)LOH:ULWH)DLOHG
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.
sysErrorString: the system error string.
Cause:
The system error should indicate the condition that caused the failure.
Effect:
The event is of critical severity.
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.
0WD+HDGHU1RW7HUPLQDWHG
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.
0WD+HDGHU5HZULWH)DLOHG
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.
580
Effect:
The current message will be placed in the deferred queue until system
resources become available
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD+RVW,QYDOLG
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.
Effect:
The event is of informational severity.
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.
0WD0D[07$+RS&RXQW([FHHGHG
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.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
581
InterMail Kx Reference Guide
0WD0HVVDJH4XHXH'LU0LVPDWFK
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.
Effect:
The event is of informational severity.
Action(s):
If control files must move to a different queue directory, make sure to
modify the Host-To: line.
0WD0HVVDJH4XHXHG7RR/RQJ
582
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.
Effect:
The event is of informational severity.
Action(s):
Determine if the remote site still exists and is reachable. If not, then
contact that site to determine the problem.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD0HVVDJH5HWXUQ6XSSUHVVHG
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.
Effect:
The event is of informational severity.
Action(s):
None.
0WD0HVVDJH6HFXUH)DLOHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
583
InterMail Kx Reference Guide
0WD0HVVDJH6HQGHU1RW$XWK
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.
Effect:
The event is of informational severity.
Action(s):
• Verify that the user's account information is correct.
• Change the /*/mta/checkAuthorization key to false.
0WD0HVVDJH7RR/DUJH
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.
584
Cause:
Someone attempted to use the server to send a message to a remote
server, but the server rejected it as being too large.
Effect:
The event is of informational severity.
Action(s):
Send smaller messages, or contact the remote site and tell them to
increase their size limit.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
07$0VJ1R5HFLSLHQWV
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.
0WD3DWK3UHIL[,QYDOLG
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.
Effect:
The event is of major severity.
Action(s):
Contact your InterMail vendor.
0WD4XHXH'LU5HPRYHG
Description:
A spool directory removed after the messages in it were processed.
Parameters:
dirName: the name of the queue directory removed.
Cause:
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
585
InterMail Kx Reference Guide
0WD4XHXH6HUYHU,WHUDWLRQ0LVPDWFK
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.
586
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD5HFLSLHQWV5HMHFWHG
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.
Effect:
The event is of informational severity.
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.
0WD5RXWH7DEOH(QWU\(UURU
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.
0WD6HQGHU5HMHFWHG
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.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
587
InterMail Kx Reference Guide
0WD6HUYHU%DG5HSO\
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.
Effect:
The event is of informational severity.
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.
0WD6HUYHU&RQQHFW)DLOHG
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.
Effect:
The event is of informational severity.
Action(s):
Wait for spool reprocessing and mail redelivery. If the condition persists,
and the host is reachable.
0WD6HUYHU'16$/RRNXS)DLOHG
588
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.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD6HUYHU'160;/RRNXS)DLOHG
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.
Effect:
The event is of informational severity.
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.
0WD6HUYHU)DLOHG
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.
Effect:
The event is of informational severity.
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.
0WD6HUYHU6RFNHW&ORVHG
Description:
Message deferred because the connection to the remote server closed.
Parameters:
None.
Cause:
The remote server most likely went down.
Effect:
The event is of informational severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
589
InterMail Kx Reference Guide
0WD6HUYHU7LPHG2XW
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.
Effect:
The event is of informational severity.
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.
0WD6HUYLFH1RW$OORZHG
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user’s account information is correct.
0WD6HUYLFH1RW$OORZHG66/
590
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.
Effect:
The event is of informational severity.
Action(s):
Verify that the user’s account information is correct.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
0WD6LGHOLQH1XOO7R0DQ\
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.
Effect:
The event is of warning severity.
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.
0WD6LGHOLQH7RR0DQ\5&37V
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.
Effect:
The event is of warning severity.
Action(s):
This is a frequent warning. One option is to increase the maximum
number of recipients in the configuration database.
Confidential and Proprietary, © Software.com, Inc. 1999
591
InterMail Kx Reference Guide
5FSW+DUYHVWHU'URSSHG
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.
Network Input/Output Log Events
1LR$FFHSW)DLO
Description:
When attempting a connection to a socket, the accept system call returns
the error systemErrorString.
Parameters:
systemErrorString: the system error string.
Cause:
• Insufficient memory to complete the accept.
• Insufficient STREAM resources to complete the accept.
592
Effect:
The event is of warning severity.
Action(s):
Use the systemErrString to determine the cause of this event.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR%DG3RUW1XPEHU
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.
1LR%DG4XHU\&RGH
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.
Action(s):
Contact your InterMail vendor.
1LR%LQG)DLO
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.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
593
InterMail Kx Reference Guide
1LR%LQG/RFDO)DLO
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.
systemErrorString: the system error string.
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.
1LR%LQG1DPH)DLO
Description:
Attempted to bind to a socket that failed with system error
systemErrorString. This happens in the MTA.
Parameters:
pgmName: the program name.
systemErrorString: the system error string.
Cause:
• Program does not have adequate permissions to access address.
• Insufficient STREAM resources.
594
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR&ORVH6RFN)DLO
Description:
The call to close the socket to host failed with system error
systemErrString.
Parameters:
host: the name of the host machine.
systemErrString: the system error string.
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.
Effect:
The event is of warning severity.
Action(s):
Verify that the server in question and the remote machine are OK.
1LR&RQ1RW$OORZHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
595
InterMail Kx Reference Guide
1LR&RQQ6HUYHU)DLO
Description:
Parameters:
This program could not connect to the server serverName on host
hostname with port portNum.
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.
1LR&RQQ7LPHRXW
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.
596
Cause:
The server or host machine host could be in a strange state. This could
indicate that the server cannot connect to the MSS.
Effect:
The event is of major severity in the context of one of the servers.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR&RQQHFW5HDG)DLO
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.
systemErrorString: the system error string.
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.
Effect:
The event is of major severity in the context of one of the servers.
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.
1LR&RQQHFWLRQ/LPLW7DEOH%DG(QWU\
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.
Confidential and Proprietary, © Software.com, Inc. 1999
597
InterMail Kx Reference Guide
1LR&UHDWH6RFNHW)DLO
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.
systemErrorString: the system error string.
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.
1LR(YHQW1RW6XSSRUWHG
Description:
An event mask eventmask specified for file descriptor filedesc which is
not supported.
Parameters:
eventmask: the event mask.
filedesc: the file descriptor.
Cause:
598
Effect:
The event is of minor severity.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR)FQWO)DLO
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.
Effect:
The event is of major severity.
Action(s):
None.
1LR)LOH1DPH7RR/RQJ
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.
1LR)LOO4XLW
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.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
599
InterMail Kx Reference Guide
1LR)LQG+RVW1DPH)DLO
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.
systemErrorString: the system error string.
Cause:
The cause depends on the system call.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Use the systemcall and the error information systemErrorString string to
determine what is wrong.
1LR*HW3RUW1XPEHU)DLO
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.
systemErrorString: the system error string.
Cause:
• Insufficient memory for operation to complete.
• Insufficient STREAMS resources.
600
Effect:
The event is major severity for the MTA.
Action(s):
Using the system error information systemErrorString determine which
condition caused this event.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR/LVWHQ)DLO
Description:
The system call to listen failed with system error systemErrorString,
when the process was establishing a connection with a client.
Parameters:
systemErrorString: the system error string.
Cause:
Network problems.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Using the error information, determine the cause of the error. If this event
occurs repeatedly, investigate network problems.
1LR0D[&RQQHFWLRQV
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.
Cause:
There are too many incoming connections.
Effect:
The event is of informational severity.
Action(s):
If these messages persist, consider raising the connection limit, or add
additional servers for an overloaded server.
1LR1R3RUW1XPEHU)RXQG
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.
Parameters:
paramName: the name of the configuration key holding the port number.
Cause:
Missing or invalid entry for the configuration key.
Effect:
The server will not run.
Action(s):
Use imconfedit to add the appropriate configuration key.
Confidential and Proprietary, © Software.com, Inc. 1999
601
InterMail Kx Reference Guide
1LR3HUPLVVLRQ(UU
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.
Effect:
The event is of major severity in the context of one of the servers.
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.
1LR3ROO%DG5HWXUQ
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.
602
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR3ROO(UU
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.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Determine the cause of the event. Check the general health of the host
machine that this process is running on.
1LR3ROO)DLO
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.
Parameters:
systemErrorString: the system error string.
Cause:
• Not enough memory for poll to complete.
• Signal caught while performing poll.
Effect:
The event is of minor severity.
Action(s):
Use the system error systemErrorString to determine the cause of the
event.
1LR3ULYLOHJHG3RUW1XPEHU
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.
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 to edit the appropriate configuration key.
Confidential and Proprietary, © Software.com, Inc. 1999
603
InterMail Kx Reference Guide
1LR5HDG6RFNHW)DLO
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.
Parameters:
systemErrorString: the system error string.
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.
1LR5HFY(UURU
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.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Look in the logs for events that would indicate either a system error or
network connection problem.
1LR5HFY)DLO
604
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.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Look in the logs for events that would indicate either a system error or
network connection problem.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR6HOHFW7LPH2XW
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.
1LR6HUYHU*RQH'RZQ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
605
InterMail Kx Reference Guide
1LR6HW%XIIHU6L]H)DLO
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.
systemErrorString: the system error string.
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.
1LR6HW0D[)GV)DLO
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.
606
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR6HW1R'HOD\
Description:
The attempt to set socket to non-blocking mode failed with system error
systemErrorString. The system call is fcntl.
Parameters:
systemErrorString: the system error string.
Cause:
• Permissions problems due to server started up with wrong user.
• Configuration
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Verify that the process started with the correct server. Verify that the
system configuration is correct.
1LR6HWVRFNRSW(UURU
Description:
The call to setsockopt() failed with system error systemErrorString.
This only happens in the context of the MSS.
Parameters:
systemErrorString: the system error string.
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.
1LR6RFNHW&ORVHG
Description:
The network connection to a client or server on host has been lost.
Parameters:
host: the name of the host machine.
Cause:
A network connection closed, or a system error occurred.
Effect:
The event is of minor severity in the context of one of the servers.
Action(s):
This is a lower level signal. Investigate the logs for more serious events.
Troubleshoot that event.
Confidential and Proprietary, © Software.com, Inc. 1999
607
InterMail Kx Reference Guide
1LR6RFNHW)DLO
Description:
The system call to socket failed with error systemErrorString.
Parameters:
systemErrorString: the system error string.
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 critical severity in the context of one of the servers.
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.
1LR6RFNHW2SHQ
Description:
Could not terminate a network connection to host properly because of a
problem with closing the socket.
Parameters:
host: the name of the host machine.
Cause:
Effect:
The event is of minor severity in the context of one of the servers.
Action(s):
Contact your InterMail vendor.
1LR6WDOH)LOH(UU
608
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.)
Parameters:
file: the file name.
Cause:
File removed during access.
Effect:
The event is of critical severity in the context of one of the servers.
Action(s):
Verify that the file exists.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
1LR6WDW)DLO
Description:
The attempt to get statistics on the file failed. Specifically, the system call
stat failed with error systemErrorString.
Parameters:
file: the file name.
systemErrorString: the system error string.
Cause:
• Permissions may not be right for process and/or file.
• The file may no longer exist.
Effect:
The event is of major severity in the context of one of the servers.
Action(s):
Use the systemErrorString to determine the cause of this event.
Parameter Log Events
3DUP1RW2SWLRQ
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.
Effect:
The event is of warning severity.
Action(s):
Verify the script or command that started the MSS to determine the valid
and invalid command line arguments.
Confidential and Proprietary, © Software.com, Inc. 1999
609
InterMail Kx Reference Guide
3DUP8QNQRZQ2SWLRQ
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.
Effect:
The event is of warning severity.
Action(s):
Verify the script or command that started the MSS to determine the valid
and invalid command line arguments.
POP Server Log Events
3RS&RPPXQLFDWLRQ(UU
610
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.
Effect:
The event is of warning severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3RS&RQQHFWLRQ1RW$OORZHG
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.
3RS&RQQ0DGH
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.
Effect:
The event is of informational severity.
Action(s):
None.
3RS&RQQ7LPHG2XW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
611
InterMail Kx Reference Guide
3RS'RPDLQ7DEOH(QWU\(UURU
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.
3RS/RFN7LPHRXW7RR$JJUHVVLYH
612
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.
Confidential and Proprietary, © Software.com, Inc. 1999
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.
Confidential and Proprietary, © Software.com, Inc. 1999
613
InterMail Kx Reference Guide
3RS0D[6HVVLRQV
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
Cause:
There are too many incoming connections.
Effect:
The event is of warning severity.
Action(s):
If these messages persist, consider raising the connection limit, or add
additional servers if the server is already overloaded.
3RS1R066
614
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.
Effect:
The event is of minor severity.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3RS3URWRFRO(UU
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.
3RS3UR[\/RRS'HWHFWHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
615
InterMail Kx Reference Guide
3RS6\QF(UURU
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):
Process Log Events
3URF$VVHUW)DLO
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
616
Cause:
An assertion failed at run-time.
Effect:
Depends on the assertion.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF%DG6WDWH&RGH
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.
3URF%DLO
lineNumber: line number in the source file
Cause:
Must be determined from source code.
Effect:
Must be determined from source code.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
617
InterMail Kx Reference Guide
3URF%URDGFDVWLQJ&RQG
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.
systemErrorString: the system error string.
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.
3URF&DQW*HW3URJ3DWK
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.
3URF&DQW.LOO3URFHVV
Description:
Could not kill the process.
Parameters:
process: the name of the process program.
pid: the process id.
systemErrorString: the system error string.
618
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF&DQW5HDG3LG)LOH
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.
3URF&DQW5H([HF3URJ
Description:
The program at the given path cannot be re-executed.
Parameters:
pathToExecutable: the path to the executable program.
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.
3URF&DW1R1DPH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
619
InterMail Kx Reference Guide
3URF&KGLU)DLO
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.
3URF&KPRG)DLO
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
620
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF&KRZQ)DLO
Description:
Failing attempt to change the ownership of a file with chown(2).
Parameters:
filename: the name of the file.
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.
3URF&ORVH)DLO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
621
InterMail Kx Reference Guide
3URF&RQG0XWH[1RW/RFNHG
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.
622
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF&RQILJ&KDQJH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
623
InterMail Kx Reference Guide
3URF'HOHWH/RFNHG0XWH[
Description:
An attempt made to delete a locked mutex.
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.
624
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF'HVWUR\&RQG)DLO
Description:
An attempt to destroy the condition named conditionName failed with the
system error given.
Parameters:
conditionName: the name of the condition.
systemErrorString: the system error string.
Cause:
Call to cond_destroy(3T) failed with the error code given. See the
man page for cond_destroy(3T).
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.
Confidential and Proprietary, © Software.com, Inc. 1999
625
InterMail Kx Reference Guide
3URF'HVWUR\0XWH[)DLO
Description:
Destroying the mutex mutexName failed. The system error is
systemErrorString.
Parameters:
mutexName: the name of the mutex.
SystemErrorString: the system error string.
Cause:
Call to mutex_destroy(3T) failed. See the man page for
mutex_destroy(3T).
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 process. 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.
3URF'XS)DLOHG
626
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.
Action(s):
Analyze reasons for failure.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF'XS6XUSULVH
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.
Effect:
Messages from third-party libraries appear on stderr.
Action(s):
Analyze reasons for failure.
3URF([F6WDFN2YIO
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.
3URF([LW
Confidential and Proprietary, © Software.com, Inc. 1999
627
InterMail Kx Reference Guide
3URF([LW&RGH
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.
3URF)DWDO6LJQDO
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:
628
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF)FKRZQ)DLO
Description:
An attempt to change the ownership of a file with fchown(2) failed.
Parameters:
filename: the name of the file.
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. 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.
3URF*HWJUQDP)DLO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
629
InterMail Kx Reference Guide
3URF*HWSZQDP)DLO
Description:
An attempt to get password file information about the user failed.
Parameters:
userName: the user name
systemErrorString: the system error string.
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.
3URF*HWSZXLG)DLO
Description:
An attempt to get the password file information about the user with a user
id failed.
Parameters:
userName: the UNIX user name.
systemErrorString: the system error string.
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.
3URF*HW7KUG3UL)DLO
Description:
An attempt to determine the thread’s priority failed.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
630
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF*HW7KUG6SHF)DLO
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.
Parameters:
systemErrorString: the system error string.
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.
3URF,QLW&RQG)DLO
Description:
An attempt to initialize a condition has failed. This is one of several
multi-threading synchronization techniques used.
Parameters:
conditionName: the name of the condition.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
631
InterMail Kx Reference Guide
3URF,QLW0XWH[)DLO
Description:
An attempt to initialize a mutex has failed. This is one of several multithreading synchronization techniques used.
Parameters:
mutexName: the name of the mutex.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF-RLQ7KUG)DLO
Description:
A call to thr_join(3T) failed with the given system error string. This
event cannot happen in the current revision of InterMail.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
632
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF.LOO7KUG)DLO
Description:
An attempt to send a signal to this thread failed.
Parameters:
threadName: could not signal the name of the thread.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF/DXQFK5HSRUW
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.
Effect:
The event is of informational severity.
Action(s):
None.
3URF/RFN$FT2UGHU
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.
Parameters:
mutexName: the name of the mutex.
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.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
633
InterMail Kx Reference Guide
3URF/RFN0XWH[)DLO
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF071RW6XSSRUWHG
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF0XWH[:DVQW/RFNHG
Description:
Attempt made by thread threadName to unlock the mutex named
mutexName, but that mutex not locked to begin with.
Parameters:
mutexName: the name of the mutex.
threadName: the name of the thread.
Cause:
634
Effect:
The event is of major to critical severity. The effect on service of this
event is unpredictable.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF1R&+)QG
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF1R)UPZUN
Description:
An attempt made to call a function in the InterMail library without
initializing the library.
Parameters:
serviceEntryName: name of the service entry.
Cause:
Effect:
The event is of major severity. The effect on service depends on the
component affected.
Action(s):
Restart the server and contact your InterMail vendor.
3URF1R5XQ'LU
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.
Confidential and Proprietary, © Software.com, Inc. 1999
635
InterMail Kx Reference Guide
3URF1XOO0XWH[
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF3LSH&UHDWH)DLOHG
Description:
A call to pipe(2) is failing.
Parameters:
systemError: the system error that occurs after the call to pipe(2)fails.
Cause:
None.
Effect:
Messages from third-party libraries appear on stderr.
Action(s):
Analyze reasons for failure.
3URF3RRO5HVRXUHFHV/RVW
Description:
An internal programming problem occurred during shutdown.
Parameters:
threadName: name of the pool manager thread.
numOfResources: the number of resources that not returned.
636
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF3URFHVV1RW5XQQLQJ
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.
3URF5H$FT/RFN)DLO
Description:
Attempt to reacquire the lock for mutex mutexName failed.
Parameters:
mutexName: the name of the mutex.
systemErrorString: the system error string.
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.
Effect:
The event is of major to critical severity. The effect on service is
unpredictable.
Action(s):
Restart the server and contact your InterMail vendor.
3URF5H([HFLQJ3URJ
Description:
The program at the given path is re-executing.
Parameters:
pathToExecutable: the path to the executable program.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
637
InterMail Kx Reference Guide
3URF6HP%DG.H\
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.
Action(s):
Contact your InterMail vendor.
3URF6HP&UHDWH)DLO
Description:
The call to semget to create semaphore semaphoreName failed with
system error systemErrorString.
Parameters:
semaphoreName: the name of the semaphore.
systemErrorString: the system error string.
Cause:
638
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF6HP*HW6WDW)DLO
Description:
The call to semctl to set status of semaphore semaphoreName is failing
with system error systemErrorString.
Parameters:
semaphoreName: the name of the semaphore.
systemErrorString: the system error string.
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.
3URF6HP1R1DPH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
639
InterMail Kx Reference Guide
3URF6HP3RVW)DLO
Description:
The call to semop to signal semaphore semaphoreName failed with
system error systemErrorString.
Parameters:
semaphoreName: the name of the semaphore.
systemErrorString: the system error string.
Cause:
The process does not have appropriate permissions.
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.
Action(s):
Verify that the process logging this event started with the correct user to
insure that the process has the appropriate permissions.
3URF6HP8QLQLWLDOL]HG
640
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.
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF6HP:DLW)DLO
Description:
The call to semop to wait on semaphore semaphoreName failed with
system error systemErrorString.
Parameters:
semaphoreName: the name of the semaphore.
systemErrorString: the system error string.
Cause:
The process does not have appropriate permissions.
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.
Action(s):
Verify that the process logging this event started with the correct user to
insure that the process has the appropriate permissions.
3URF6HWJLG1XP
Description:
An attempt to set the group id of the process failed with the system error
given.
Parameters:
groupId: the (numeric) group id.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
641
InterMail Kx Reference Guide
3URF6HW0D[3WKUHDGV)DLO
Description:
Could not increase the number of threads.
Parameters:
None.
Cause:
Effect:
The event is of major severity.
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.
3URF6HW7KUG3UL)DLO
Description:
A call to thr_setpriority(3T) failed with the system error given.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
Cause:
Effect:
The event is of major to critical severity level. The effect on service of
this event is unpredictable.
Action(s):
Restart the server and contact your InterMail vendor.
3URF6HW7KUG6SHF)DLO
Description:
When creating a thread an error occurs when setting thread-specific data.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
642
Cause:
A call to thr_setspecific(3T) failed with the system error given.
Effect:
The event is of major to critical severity. The effect on service is
unpredictable.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF6HW7KUHDG&DSDELOLW\)DLOHG
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.
3URF6HWXLG1XP
Description:
An attempt to set the user id of the process failed with the system error
code given.
Parameters:
userName: the name of the user.
systemErrorString: the system error string.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
643
InterMail Kx Reference Guide
3URF6HWXLG6XFFHHG
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.
3URF6KXWGRZQ
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).
644
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF6KXWGRZQ,Q3URJUHVV
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.
3URF6KXWGRZQ3UHHPSWHG
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.
3URF6KXWGRZQ5HTXHVWHG
Description:
Program requested to shutdown.
Parameters:
None.
Cause:
Process killed with a SIGHUP and is exiting gracefully.
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
645
InterMail Kx Reference Guide
3URF6KXWGRZQ6HTXHQFH(UURU
Description:
This event indicates a programming error in InterMail code.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
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.
3URF6KXWGRZQ6WDOOHG
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.
646
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF6LJQDO&RQG)DLO
Description:
An attempt to signal the condition conditionName resulted in a system
error.
Parameters:
conditionName: the name of the condition.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF6LJQDOOHG
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF6XVS7KUG)DLO
Description:
An attempt to suspend a thread has failed.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
Cause:
Effect:
The effect on service is not predictable. This is a major or critical error.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
647
InterMail Kx Reference Guide
3URF7KUG$WWU'HVWUR\
Description:
When attempting to destroy the attribute data for thread threadName
encountered error systemErrorString. This was because of calling
pthread_attr_destroy.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
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):
Using the information from systemErrorString determine the cause of
this event.
3URF7KUG$WWU,QLW)DLO
Description:
When creating a new per-thread data for thread threadName encountered
error systemErrorString. This was because of calling
pthread_attr_init.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
648
Cause:
Memory exhausted or programming error.
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):
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF7KUG.H\&UHDWH)DLO
Description:
When creating a new per-thread data key for thread threadName an error
encountered.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF7KUG0DLQ&DOOHG
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.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
649
InterMail Kx Reference Guide
3URF7KUG6FKHG)DLO
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.
Parameters:
threadName: the name of the thread.
systemErrorString: the system error string.
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):
Using the information from systemErrorString determine the cause of
this event.
3URF7KUG6HW6WDFNVL]H
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.
systemErrorString: the system error string.
Cause:
Memory exhausted or stack size exceeds system limit.
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):
• 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.
650
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
3URF7RR0DQ\)DWDOV
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.
3URF8QFDXJKW&3OXV3OXV([FHSWLRQ
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.
Action(s):
Contact your InterMail vendor.
3URF8QORFN0XWH[)DLO
Description:
An attempt to unlock a mutex has failed with the system error given.
Parameters:
mutexName: the name of the mutex.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
651
InterMail Kx Reference Guide
3URF:DLW2Q&RQG)DLO
Description:
An attempt to wait on a condition has failed with the system error given.
Parameters:
conditionName: the name of the condition.
systemErrorString: the system error string.
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.
Action(s):
Restart the server and contact your InterMail vendor.
3URF:ULWH7R6WGHUU
652
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.
Action(s):
Contact your InterMail vendor.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
RME Log Events
5PH%DG&OLHQW5HI
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.
5PH%DG'LU&DFKH+RVW
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.
Confidential and Proprietary, © Software.com, Inc. 1999
653
InterMail Kx Reference Guide
5PH%XIIHU2YHUUXQ
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:
Effect:
The event is of critical severity.
Action(s):
Contact your InterMail vendor.
5PH&OLHQW7LPHRXW
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.
5PH&OLHQW7LPHRXW
654
Description:
While waiting for a response for an RME operation, the operation timed
out.
Parameters:
server name: the name of the server.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PH&RQQHFWLRQ8QDYDLODEOH
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.
5PH'LU&DFKH'RZQ
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.
Action(s):
Check the status of the host machine. If the error is repeating several
times a minute, check network status.
5PH'LU&DFKHXS
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.
Confidential and Proprietary, © Software.com, Inc. 1999
655
InterMail Kx Reference Guide
5PH)LOO(UURU
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.
5PH1R+RVW1DPH
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.
5PH1XOO'HVW
656
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PH2S1RW6XSSRUWHG
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.
Confidential and Proprietary, © Software.com, Inc. 1999
657
InterMail Kx Reference Guide
5PH3URWR%DG'DWD)PW
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.
5PH3URWR%DG/HQJWK
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.
658
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PH3URWRFRO(UU
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.
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.
5PH3URWRFRO0LVPDWFK
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.
Effect:
The event is of minor severity. However, if error floods, many users may
be 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.
Confidential and Proprietary, © Software.com, Inc. 1999
659
InterMail Kx Reference Guide
5PH6HUYHU&ORVHG6RFNHW
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.
Effect:
The event is of minor severity.
Action(s):
Check the log file for indications of other problems that may have
possibly caused this.
5PH6WDOH5HI
660
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.
Effect:
The event is of minor severity. However, if error floods, many users may
be affected.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PH8QELQG:LWK1R%LQG
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.
5PH8QH[SHFWHG5HWXUQ
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.
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 the network status.
Confidential and Proprietary, © Software.com, Inc. 1999
661
InterMail Kx Reference Guide
5PH8QH[SHFWHG5HWXUQ
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.
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 error is repeating several times a
minute, check the network status.
Remote Control Server Log Events
5PW%DG([LW6WDWXV
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.
Action(s):
Analyze reasons for failure.
5PW&KLOG)VWDW)DLO
Description:
A call to fstat(2) failed.
Parameters:
systemError: the system error after the failed call to fstat(2).
Cause:
662
Effect:
The output from the child process may be lost.
Action(s):
Analyze reasons for failure.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PW&RPPDQG7UDFH
Description:
Shows the exact command-line invocation of imctrl.
Parameters:
invocation: the exact command line invocation of imctrl.
Cause:
Effect:
None.
Action(s):
None.
5PW&RQWUDGLFWRU\9HUEV(UURU
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.
5PW'LGQW'LH
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.
Action(s):
Analyze reasons for failure.
Confidential and Proprietary, © Software.com, Inc. 1999
663
InterMail Kx Reference Guide
5PW'XS)DLOHG
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:
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
5PW'XS6XUSULVH
Description:
Parameters:
A call to dup(2) return an unexpected fd.
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.
Action(s):
Analyze reasons for failure.
5PW([HF)DLOHG
Description:
A call to exec(2) failed.
Parameters:
systemError: the system error after the failed call to exec(2).
Cause:
664
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PW)RUN)DLOHG
Description:
A call to fork1(2) failed.
Parameters:
systemError: the system error after the failed call to fork1(2)
Cause:
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
5PW,OOHJDO+RVW
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.
5PW3LSH&UHDWH)DLOHG
Description:
A call to pipe failed.
Parameters:
systemError: the system error after the failed call to pipe(2).
Cause:
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
Confidential and Proprietary, © Software.com, Inc. 1999
665
InterMail Kx Reference Guide
5PW3URFHVV6LJQDOOHG
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:
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
5PW50()DLOHG
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.
5PW50(6XFFHHGHG
Description:
The RME command succeeded.
Parameters:
RME: the RME it is performing.
Cause:
666
Effect:
None.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
5PW6WDUWLQJ50(
Description:
Starting an RME command.
Parameters:
RME: the RME it is performing.
Cause:
Effect:
None. The event is of informational severity.
Action(s):
None.
5PW:DLWSLG7LPHRXW
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:
Effect:
Actions requested of immgrserv not carried out.
Action(s):
Analyze reasons for failure.
5XQ3RS/RFNHG([FOXVLYH
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.
Confidential and Proprietary, © Software.com, Inc. 1999
667
InterMail Kx Reference Guide
SMTP Log Events
6PWS$GGUHVV)L[HG
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.
Effect:
The event is of informational severity.
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.
6PWS%DG5HOD\3ROLF\
668
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS&OLHQW*UHHW5HVSRQVH
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.
6PWS&OLHQW/LQH7RR/RQJ
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).
Confidential and Proprietary, © Software.com, Inc. 1999
669
InterMail Kx Reference Guide
6PWS&OLHQW0DLO/RRS'HWHFWHG
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.
6PWS&OLHQW1R*UHHWLQJ
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.
670
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS&OLHQW1R5HVSRQVH
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.
Effect:
The event is of informational severity.
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.
6PWS&OLHQW5HVSRQVH
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.
Effect:
The event is of informational severity.
Action(s):
Check the logs for subsequent SmtpMessageDeferred or
SmtpMessageDelivered entries to see which message affected.
Confidential and Proprietary, © Software.com, Inc. 1999
671
InterMail Kx Reference Guide
6PWS&RQQHFWLRQ&ORVHG
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.
Effect:
The event is of informational severity.
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.
6PWS&RQQHFWLRQ'URSSHG
672
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.
Effect:
The event is of warning severity.
Action(s):
If this is not the desired result, disable the dropConnections feature.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS&RQQHFWLRQ'URSSHG5&37
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.
Effect:
The event is of warning severity.
Action(s):
If this behavior is correct, ignore this warning. Otherwise, modify the
dropMaxMessageRCPTs configuration key appropriately.
6PWS&RQQHFWLRQ5HFHLYHG
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.
Effect:
The event is of informational severity.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
673
InterMail Kx Reference Guide
6PWS&RQQHFWLRQ7LPHRXW
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.
6PWS'QV%DG&RQILJ
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.
Effect:
The event is of informational severity.
Action(s):
Look up the MX and A records of the domain (using nslookup).
6PWS'QV/RRNXS)DLOHG
674
Description:
A DNS lookup of the domain failed.
Parameters:
domainName: the domain name.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS'QV/RRNXS7LPHG2XW
Description:
A DNS lookup of the domain timed out.
Parameters:
domainName: the domain name.
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.
6PWS'RPDLQ1DPH8QNQRZQ
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.
Parameters:
domainName: the domain name.
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.
6PWS+RVW1RW)RXQG
Description:
The specified host does not exist.
Parameters:
domainName: the domain name.
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.
Effect:
The event is of informational severity.
Action(s):
Look up the domain in the DNS (using nslookup‘).
Confidential and Proprietary, © Software.com, Inc. 1999
675
InterMail Kx Reference Guide
6PWS,OOHJDO8VHU1DPH
Description:
A message addressed to a user at a local domain, but the user name
(everything before the @ in the address) contains illegal characters.
Parameters:
userName: the user name.
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.
6PWS0HVVDJH&RPPLW7R'LVN)DLOHG
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.
676
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS0HVVDJH'HIHU)LOH6WXFN
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.
Parameters:
filename: the name of the file.
systemErrorString: the system error string.
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.
6PWS0HVVDJH1R6SDFH
Description:
Parameters:
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.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
677
InterMail Kx Reference Guide
6PWS0HVVDJH7RR%LJ
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.
Effect:
The event is of informational severity.
Action(s):
NA.
6PWS1DPH7RR/RQJ
678
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.
Parameters:
userName: the user name.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS3URWRFRO1RW6XSSRUWHG
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.
Effect:
The event is of informational severity.
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).
6PWS4XHXH3URFHVV
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.
Effect:
The event is of informational severity.
Action(s):
None.
6PWS5HFLSLHQW5HMHFWHG6HQGHU1XOO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
679
InterMail Kx Reference Guide
6PWS5HOD\3UHYHQWHG
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.
Effect:
The event is of warning severity.
Action(s):
If this is not the intended behavior, modify the relay configuration keys
appropriately. Otherwise, ignore this warning.
6PWS6HQGHU$GGU,QYDOLG
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:.
6PWS6HQGHU%ORFNHG
680
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.
Effect:
The event is of informational severity.
Action(s):
If this behavior is correct, ignore the event. Otherwise, modify the block
configuration key(s) appropriately.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS6HQGHU'RPDLQ&DQW9HULI\
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 reattempts the delivery, the message will be accepted if the DNS can
resolve the domain name. Otherwise, it will remain queued.
Action(s):
None.
6PWS6HQGHU'RPDLQ,V,3$GGUHVV
Description:
A message rejected because the sender’s address contains an IP address
for a domain (such as <user@[10.20.30.40]>).
Parameters:
sender: the sender of the message.
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.
6PWS6HQGHU'RPDLQ0LVVLQJ
Description:
Message rejected because the sender’s address does not have a domain.
Parameters:
sender: the sender of the message.
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 email (UCE, commonly known as spam).
Effect:
Messages from senders without domains rejected.
Action(s):
None.
Confidential and Proprietary, © Software.com, Inc. 1999
681
InterMail Kx Reference Guide
6PWS6HQGHU'RPDLQ1RQH[LVWHQW
Description:
Message rejected because the sender’s address contains a domain not
found in the domain name system (DNS).
Parameters:
sender: the sender of the message.
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 email (UCE, commonly known as spam).
Effect:
Messages from senders with bad domains rejected.
Action(s):
None.
6PWS6HUYHU%DG8VDJH
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.
682
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.
Effect:
The event is of informational severity.
Action(s):
Ignore.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS6HUYHU&RPPDQG8QNQRZQ
Description:
The connected SMTP client issued an unrecognized command, which
was ignored.
Parameters:
domainName: the domain name.
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.
Effect:
The event is of informational severity.
Action(s):
6PWS6HUYHU(WUQ,VVXHG
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):
Confidential and Proprietary, © Software.com, Inc. 1999
683
InterMail Kx Reference Guide
6PWS6HUYHU([SQ,VVXHG
Description:
Parameters:
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.
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.
6PWS6HUYHU+DFNHU$OHUW
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.
Parameters:
domainName: the client’s domain name.
command: the command attempted.
684
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS6HUYHU4VQG,VVXHG
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.
Parameters:
domainName: the client’s domain name.
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.
6PWS6HUYHU5HVSRQVH2YHUIORZ
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.
Confidential and Proprietary, © Software.com, Inc. 1999
685
InterMail Kx Reference Guide
6PWS6HUYHU7RR0DQ\%DG&RPPDQGV
Description:
The SMTP client issued too many invalid commands, so the connection
closed.
Parameters:
domainName: the client’s domain name.
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.
Effect:
The event is of informational severity.
Action(s):
Ignore, or look for previously logged events for SmtpServerBadUsage
and SmtpServerCommandUnknown to see what the bad commands
were.
6PWS6HUYHU9UI\,VVXHG
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.
Parameters:
domainName: the client’s domain name.
address: the address to verify.
686
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.
Effect:
The event is of informational severity.
Action(s):
You can turn off the VRFY command by modifying the /*/mta/
allowVrfy configuration key.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6PWS6LGHOLQH0D[5&37V([FHHGHG
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.
6QPS&DQW&RQQHFW7R0DVWHU$JHQW
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 postinstall values, or at least to -nosnmp.
Confidential and Proprietary, © Software.com, Inc. 1999
687
InterMail Kx Reference Guide
6QPS,QLW)DLOHG
Description:
The call to InitSubAgent() in the Emanate library failed.
Parameters:
None.
Cause:
None.
Effect:
The particular server runs, but is not SNMP-enabled.
Action(s):
Analyze reasons for failure.
6QPS1R,S$GGU
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.
SSL Log Events
6VO&RQILJ
688
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.
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6VO'%,QLW
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 nonSSL 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.
6VO+DQGVKDNH
Description:
The first SSL negotiation phase (handshake) between the client and
server did not complete successfully.
Parameters:
sslErrorString: a descriptive character string derived from the code
defined by SSLPLUS, indicating the error condition.
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.
Confidential and Proprietary, © Software.com, Inc. 1999
689
InterMail Kx Reference Guide
6VO7/6+DQGVKDNH
Description:
An error occurred during the SSL handshake phase when the client uses
TLS command to initiate a secure session.
Parameters:
sslErrorString: a descriptive character string derived from the code
defined by SSLPLUS, indicating the error condition.
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.
System Log Events
6\V+HDS&RUUXSWHG
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.
690
Confidential and Proprietary, © Software.com, Inc. 1999
Log Events
6\V067DEOH)XOO
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.
6\V0DOORF)DLO
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.
Confidential and Proprietary, © Software.com, Inc. 1999
691
InterMail Kx Reference Guide
6\V1R6SDFH
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.
692
Confidential and Proprietary, © Software.com, Inc. 1999
A
Configuration 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 Keys
The 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
Confidential and Proprietary, © Software.com, Inc. 1999
693
InterMail Kx Reference Guide
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
694
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
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
•
•
•
•
•
•
•
•
•
•
•
•
sharedDir
statNamedPipeMode
statRecorderSize
tmpDir
traceNamedPipeMode
traceOutputLevel
traceRecorderSize
traceToStderr
updateServerDN
useBoundThreads
useMmapReads
useMmapWrites
MTA Configuration Keys
The 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
Confidential and Proprietary, © Software.com, Inc. 1999
695
InterMail Kx Reference Guide
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
696
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
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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
Confidential and Proprietary, © Software.com, Inc. 1999
697
InterMail Kx Reference Guide
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
698
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
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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
Confidential and Proprietary, © Software.com, Inc. 1999
699
InterMail Kx Reference Guide
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
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 Keys
The keys listed below control the behavior of the Message Store Server (MSS).
adminMessageStoreName
autoReplyDefaultMessage
autoReplyExpireDays
backupMode
bounceQuotaNotice
700
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
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
Confidential and Proprietary, © Software.com, Inc. 1999
701
InterMail Kx Reference Guide
Directory Server Configuration Keys
The keys listed below control the behavior of the Directory server.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
702
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
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
•
numUserDBFiles
POP Server Configuration Keys
The keys listed below control the behavior of the POP server.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
allowedIPs
badPasswordDelay
badPasswordWindow
clientTimeout
createsMboxes
dirRmeConnections
dirRmeMaxSecondaryCalls
initClientTimeout
lockTimeout
loginDefaultDomain
loginDefaultDomainTable
logMailBoxCreation
maxBadPassword
maxBadPasswordAddrs
maxBadPasswordDelay
maxBadPasswordUsers
maxPasswordFailures
maxSessions
moveRetrieveErrors
pop3Port
popProxyHost
popProxyPort
sslCacheAgeSeconds
sslCacheBucketLen
sslCacheBucketNum
sslCertChainPathAndFile
sslCertPassword
sslPop3Port
Confidential and Proprietary, © Software.com, Inc. 1999
703
InterMail Kx Reference Guide
•
•
sslTrustedCertPathAndFile
sslUseSessionCache
IMAP Server Configuration Keys
The keys listed below control the behavior of the IMAP server.
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
704
badPasswordDelay
badPasswordWindow
clientTimeout
createsMboxes
dirRmeConnections
dirServName
dirRmeMaxSecondaryCalls
imap4Port
loginDefaultDomain
loginDefaultDomainTable
logMailBoxCreation
maxBadPassword
maxBadPasswordAddrs
maxBadPasswordDelay
maxBadPasswordUsers
maxKeywordLength
maxMsgTextCache
maxPasswordFailures
maxSessions
sslCacheAgeSeconds
sslCacheBucketLen
sslCacheBucketNum
sslCertPassword
sslImap4Port
sslUseSessionCache
Confidential and Proprietary, © Software.com, Inc. 1999
Configuration Keys by Server
Configuration Server Configuration Keys
The keys listed below control the behavior of the Configuration server.
•
•
•
•
confServPort
extraCopyConfigDbPath
serverTimeout
versionConfigDB
Manager Server Configuration Keys
The keys listed below control the behavior of the Manager server.
•
•
legalHosts
mgrServPort
SNMP Server Configuration Keys
The keys listed below control the behavior of the SNMP server.
•
•
•
•
masterAgentHosts
snmpReconnectNapTime
trapMask
trapQueueSize
Confidential and Proprietary, © Software.com, Inc. 1999
705
InterMail Kx Reference Guide
706
Confidential and Proprietary, © Software.com, Inc. 1999
B
Supported 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
Confidential and Proprietary, © Software.com, Inc. 1999
707
InterMail Kx Reference Guide
708
RFC
Title
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
Confidential and Proprietary, © Software.com, Inc. 1999
C
License Information
This appendix contains license information related to InterMail Kx.
InterMail Licensing Agreement
THIS 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, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (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 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 License
Redistribution 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-
Confidential and Proprietary, © Software.com, Inc. 1999
709
InterMail Kx Reference Guide
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 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.
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 Supercomputing 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.
EMANATE
InterMail 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 contrast, 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 software 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 recipients 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 recipients 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.
710
Confidential and Proprietary, © Software.com, Inc. 1999
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 utility 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 effectively 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 benefit 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 Public 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 outside 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.
Confidential and Proprietary, © Software.com, Inc. 1999
711
InterMail Kx Reference Guide
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 welldefined independent of the application. Therefore, Subsection 2d requires that any application-supplied 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 permissions 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 General 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 offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with
the object code.
5.
712
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.
Confidential and Proprietary, © Software.com, Inc. 1999
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 distribution 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 customer'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 containing 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 performing 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, uncombined with any other library facilities. This must be distributed under the terms of the Sections
above.
Confidential and Proprietary, © Software.com, Inc. 1999
713
InterMail Kx Reference Guide
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 provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute 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 automatically 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 recipients’ 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 conditions 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 Foundation. If the Library does not specify a license version number, you may choose any version ever
published by the Free Software Foundation.
14.
714
If you wish to incorporate parts of the Library into other free programs whose distribution conditions 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-
Confidential and Proprietary, © Software.com, Inc. 1999
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 generally.
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 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 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 REDISTRIBUTE 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 SUSTAINED 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.
Oracle
Oracle Programs are the proprietary products of Oracle and are protected by copyright and other intellectual 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 California. 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 distribution.
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, Berkeley and its contributors.
4.
Neither the name of the University nor the names of its contributors may be used to endorse or promote 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
Confidential and Proprietary, © Software.com, Inc. 1999
715
InterMail Kx Reference Guide
DAMAGES (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
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 Routines
1.
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 original 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.
716
Confidential and Proprietary, © Software.com, Inc. 1999
Glossary
absolute pathname
The path to a file beginning at the root directory. See also relative pathname.
account
A 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 value
A 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 status
An 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 completion
The 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 john.doe@software.com.
Address completion is carried out only when a message would be otherwise
undeliverable because of an address error.
Confidential and Proprietary, © Software.com, Inc. 1999
717
InterMail Kx Reference Guide
administration utility
A 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 mailbox
A 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.
alias
1. 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.
attachment
Portions 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.
attribute
Information 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 constraint
An 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 value
The data associated with an attribute. For example, 555-1212 is an attribute value
for the attribute telephoneNumber. Attributes may be single-valued or multiplevalued.
authentication
The 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.
718
Confidential and Proprietary, © Software.com, Inc. 1999
Glossary
auto-reply feature
A feature associated with InterMail accounts. When mail arrives for an account
that uses the auto-reply feature, InterMail automatically sends the account’s autoreply message to the sender of the original message.
availability
See high availability.
blocking
See mail blocking.
Body file
A 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 message
A message that the MSS transmits to the sender of a message that has bounced.
Also called bounce notice.
bouncing
The process of returning an undeliverable message to its sender.
bucket
A 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.
canonicalization
A 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.
certificate
A key used as part of an authentication strategy for users. InterMail uses
certificates during MTA and all transactions involving SSL.
child process
A process created by another process. The creating process is the parent process.
class of service
A 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.
Confidential and Proprietary, © Software.com, Inc. 1999
719
InterMail Kx Reference Guide
class-of-service attribute
An 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 rule
A value that defines the relationship between a class-of-service attribute and the
account class-of-service attribute values (for example, whether the account classof-service attribute value takes precedence over the class-of-service attribute
value).
class-of-service attribute value
The 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 database
The text file that contains all configuration keys and their associated values.
configuration key
A 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 server
The 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 server
The destination server for replicated data. In InterMail, the consumer server is the
Directory Cache server.
Control file
A 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.
cookie
A 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.
720
Confidential and Proprietary, © Software.com, Inc. 1999
Glossary
deferred mail
Mail 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 server
A 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 database
A 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 server
The 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 array
A 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 striping
The writing of data blocks across mul