System Administration

Sections and Access Rights Base Directory Structure General Settings Specifying the Preferred Language Command Line Options Specifying Command Line Options under Windows NT/2000/XP Customizing Unix Startup Scripts Customizing OpenVMS Startup Procedures Shutting Down OS syslog Server Root Privilege Domain Administration Domains Administrators in other Domains WebAdmin Preferences Customizing Domain WebAdmin Interface Customizing Server Prompts Domain Name Resolver (DNR) Network Address Lists External Helper Programs When the CommuniGate Pro Server is up and running, it can be configured, monitored, and set up using any Web browser. By default, the HTTP module provides access to the CommuniGate Pro administration pages (WebAdmin Interface) via the TCP port number 8010. To connect to the server, the administrator should type http://serveraddress:8010 where serveraddress is either server IP address or the server domain name (A-record). Note: If you use a Netscape® browser, check that its caching setting (Preferences->Advanced->Cache) is set to Every time.

Sections and Privileges

The Server administration pages are divided into four groups (realms). To access a page in any group, a user should be registered with the CommuniGate Pro Server (should have an Account on the Server), and the user should be explicitly granted access rights to that section.

• The Settings section contains pages that allow a system administrator to modify the Server kernel and module settings.
• The Accounts and Domains section contains pages that allow a system administrator to create and remove secondary domains and accounts, and to modify the domain and account settings.
• The Directory section contains pages that allow a system administrator to configure the Directory services of the CommuniGate Pro server.
• The Monitors section contains pages that allow a system administrator to monitor server and module queues, communication channels and their states, and to browse the Server Logs. If a user is granted an access right to the Monitors section, additional Monitor Access rights can be granted, too (rights to release and reject module queues, reconfigure the Log Manager, etc.)
• The Master section contains the pages that allow a system administrator to grant and revoke access rights, and to modify the Server License Keys.

Note: If a user is granted the Master access right, that user can access all other sections.

Note: These access rights can be granted to the accounts (users) in the main domain only. Accounts in secondary domains can be granted domain administration rights only.

When a Server is installed for the first time, it creates the postmaster account in the main domain, assigns a random password to that account, and grants the Master access right to the postmaster user.

Base Directory Structure

All CommuniGate Pro Server files - accounts, domains, mailboxes, settings, queues, etc. are stored in one place - in the Server base directory.

When the Server starts, it creates the following objects inside its base directory:

• The Settings directory. This directory contains files with module and kernel component settings.
• The Queue directory. This directory contains Temporary and Message files. The Message files contain messages submitted to the Server, but still undelivered to all their recipients.
• BadFiles directory. This directory contains Message files the Enqueuer kernel component failed to parse. This directory should be empty.
• Accounts directory. This directory contains account files for the Main Server Domain.
• Domains directory. This directory contains directories for all Secondary Domains.
• Submitted directory. This drop-in directory is used to submit messages to Server via the PIPE module.
• SystemLogs directory. This directory contains Server Logs.
• ProcessID file. This file exists only when the Server is running and contains the numeric identificator of the Server process.
• Directory file. This file contains or describes the Server Central Directory.

For more information about the Account and Domain files and directories, see the Account Data section.

You can use symbolic links to move some of these directories to other locations (and other disks).

General Settings

Start configuring the Server by opening the General page in the Settings section.

Main Domain Name:   System Internals Log: Crashes OnlyFailuresMajor & FailuresProblemsLow-LevelAll Info   Crash Recovery: DisabledEnabled   Server Time: 21:08:46 -0800   Server Up-Time: 118 days, 0h 1m 3s   Server OS: Sun Solaris Server Hardware: Intel   Server Version: 4.2   MAPI Version: 1.1.20   Server IP Address(es): [216.200.213.118],[216.200.213.119],[10.0.0.5] Name Server(s) IP Address(es): [216.200.213.113],[216.200.213.114]

Main Domain Name

In this field you should enter the name that the CommuniGate Pro Server will interpret as its own Main Domain Name. All mail addressed to that domain will be treated as local, and (in the simplest case) that mail will be stored in local account mailboxes. Initially, this field contains the server computer name that CommuniGate Pro retrieves from the OS. If this names looks like host12345hh.company.com, you should change it to the name of the domain this Server should process.

Note: unless you create additional Domains ONLY the messages directed to addresses in the Main Domain will be processed as local. If the Main Domain Name is entered as company.com, then messages to mail.company.com will not be processed as local, and if such a message is received, the server will try to deliver it to the mail.company.com system over the network. If the DNS record for the mail.company.com points to the same Server computer, the mail loop error will be detected, and the message will be rejected.

If your server should process mail for several domains, enter the additional domain names as Main Domain Aliases (if those domain names should be mapped to the Main Domain), or create additional Secondary Domains.

Sample configuration:

A server should process mail for the company.com and client1.com domains. In the DNS system, these domain names have only MX-records pointing to mail.company.com and mail.client1.com A-records, and these A-records point to IP address(es) belonging to the CommuniGate Pro Server system.

• set company.com as the Main Domain Name.
• open the Domains page, find the company.com record and click on its Settings link to open the company.com Domain Settings page. Scroll it down to find the Aliases fields.
• enter mail.company.com into an empty Aliases field, and click the Update button.
• open the Domains page. Enter client1.com into the text field and click the Create Domain button.
• the client1.com record should appear in the list; click its Settings link to open the client1.com Domain Settings page. Scroll it down to find the Aliases fields.
• enter mail.client1.com into an empty Aliases field, and click the Update button.

System Internals Log

Use this setting to specify what kind of information the server kernel module should put in the Server Log. Usually you should use the Major (message transfer reports) level. But when you experience problems with the server kernel, you may want to set the Log Level setting to Low-Level or All Info: in this case low-level details will be recorded in the System Log as well. When the problem is solved, set the Log Level setting to its regular value, otherwise your System Log files will grow in size very quickly.
The kernel records in the System Log are marked with the SYSTEM tag.

Kernel problems are very unlikely to happen. If you see any problem with the Server, try to detect which component is causing it, and change the Log setting of that component (Router, SMTP, POP, etc.) to get more information.

Crash Recovery

If this option is enabled, the CommuniGate Pro Server uses special recovery techniques to proceed after various failures (including the crashing bugs in the Server software itself).

If you see "exception raised" messages in your CommuniGate Pro Log and/or in the OS system.log or mail.log, you may want to disable this option and force the Server to stop when an exception is raised again, and to produce a core dump file.
Core dump files can be uploaded to the Stalker ftp site for examination.

Stalker Software recommends you to disable this option if you are running any beta-version of the CommuniGate Pro software.

Information fields

Information fields on the General Settings page display the name of the Server Operating System, the hardware platform, the version of the CommuniGate Pro Server, the version of the MAPI Connector server part, the Server network address(es), the Server Local Time and Time Zone. This information is useful for system administrators that have to examine Logs from remote locations, as all time stamps in the System Logs are specified in the Server local time.

Refresh

This button can be used after the Server OS local IP Addresses have been changed or the DNS settings for CommuniGate Pro Domains have been modified. When you click this button:

• the Server re-reads the list of Local IP Addresses from the OS;
• the Server re-reads the Domain Name Server addresses from the OS settings.
• the Server updates the "Assigned IP Addresses" for all Server Domains. If some domains have IP Addresses specified "Using DNS A/MX Records", the new addresses are retrieved from the DNS system;
• the Server re-loads the MAPI Connector server part (so you can upgrade the MAPI Connector server part without restarting the Server).

Drop Root

This button is available on certain Unix platforms. It allows the System Administrator to tell the server to drop the "superuser" privileges. Certain functions (such as OS Authentication, Execute Rules operations, etc.) may become unavailable.
If the Server succeeds to drop the "superuser" privileges, the button title changes to Restore Root. Click the Restore Root button to restore the "superuser" privileges.

Specifying the Preferred Language

CommuniGate Pro supports multiple languages, and different users can use different languages. If most of your users will use the same language, it is recommended to set this language as the default one for the entire Server or for a particular Domain.

Open the Account Defaults page in the Domains section of the WebAdmin Interface if you want to set the Server-wide default language. If you want to set a default language for a particular Domain, open the Domains page of the WebAdmin Interface, open the Accounts or Settings page for the selected Domain and open the Domain Account Defaults page from there. Click the WebUser Preferences link to open the Default WebUser Preferences page.

Select the default Language and select a matching Preferred Character set: ISO-2022-JP for Japanese, KOI8-R for Russian, etc. If most of your users use modern Web browsers with the proper UTF-8 support, set the Use UTF-8 option to Reading and Composing.

Set the display names for the INBOX mailbox and the virtual MAPI Outbox folder. These strings are used only with the CommuniGate Pro own client components - the WebUser Interface and MAPI, so you can enter any valid mailbox name here, in any language. You can also change these names at any time.

Set the names for special mailboxes - Sent, Drafts, Notes, Trash, Contacts, Calendar, and Tasks. Please note that these names will be used with the CommuniGate Pro own client components only - the WebUser Interface and MAPI. To make the user's IMAP clients use the same mailboxes for the same purposes, the same mailbox names should be specified in the IMAP client configurations. If you change these names later, the new mailboxes will be created when a client needs to access a special mailbox: the already existing special mailboxes will not be renamed.

Command Line Options

The CommuniGate Pro Server supports the following command-line options (parameters):

--CGateBase directory
or
--Base directory

The next parameter string specifies the location of the CommuniGate Pro base directory.

--LogToConsole

This option tells the Server to duplicate all its System Log records to the stdout (standard output). This option can be used for troubleshooting when the Web interface to System Logs is not available.

--LogAll

This option tells the Server to ignore all current Log Level settings and record all possible Log records.

--NoWebCache

This option tells the server not to cache the Web Interface files internally. Use this option when you modify the Web Interface files and you need to see the results without restarting the server.

--Daemon

This option can be specified on Unix platforms only. It tells the server to fork and operate in the background, with stdin, stdout, and stderr redirected to /dev/null.

--CGateApplication directory

The next parameter string specifies the location of the CommuniGate Pro application directory. You can use this option when the application itself cannot properly detect its own location, or if the CommuniGate Pro Server application file is not placed in the same location as other application directory files and subdirectories. For example, on OS/400 CommuniGate Pro Server is located in an OS/400 library, and this parameter is used to tell the server where the Unix-style directory with WebUser, WebAdmin, WebGuide, and other files is located.

--noLockFile

This option tells the Server not to create the ProcessID lock file. This option can be used if the file system hosting the base directory does not support file locks.

--dropRoot

This option can be specified on Unix platforms only (this does not include Linux). It tells the Server to drop the root privilege permanently. The server drops the privilege aproximately 60 seconds after the end of its kernel initiatialization process, so all listenening sockets can be opened when the server is still running as the root. The root privilege cannot be restored later. See the Server Root Privilege section for more details.

--ThreadsScope

This option can be specified on platforms supporting p-threads (OS/400 and most Unix flavors). The next parameter string can be either "system" or "process". See your OS manual to learn how these "scheduling scopes" work. If this option is not specified, the default OS scheduling mode is used.

--BatchLogon

This option can be specified on Microsoft Windows NT/2000/XP platforms only.
The option tells the Server to use 'batch logon' instead of the 'network logon' when an account password is verified using the Windows OS password system.

--SharedFiles

This option can be specified on Microsoft Windows and IBM OS/2 platforms only.
The option tells the Server to open all files with the FILE_SHARE_READ sharing attribute making it possible for other programs (such as backup daemons) read the CommuniGate Pro base directory files when the server is running.

--useNonBlockingSockets

This option tells the Server to set its TCP/IP sockets in the non-blocking mode. This option can improve the Server performance on some platforms.

--useBlockingSockets

This option tells the Server to set its TCP/IP sockets in the blocking mode.

--closeStuckSockets

This option tells the Server to maintain a list of open communication sockets and check if some socket operations did not complete in time and due to the kernel bugs the OS failed to interrupt the operation in time. It is recommended to use this option on heavly-loaded Solaris systems.

Command line option names are case-insensitive.

Specifying Command Line Options under Windows NT/2000/XP

You can specify the Command Line Options using the Services control panel "Startup Parameters" field. A non-empty set of Command Line Options is stored in the System Registry and it is used every time the CommuniGate Pro Messaging Server service is started without parameters. To clear the stored set of the Command Line Options, specify a single "-" sign using the Services control panel "Startup Parameters" field.

Customizing Unix Startup Scripts

You may need to add certain shell commands to the CommuniGate Startup script. Since the Startup script is a part of CommuniGate Pro application software, it is overwritten every time you upgrade your CommuniGate Pro system. Instead of modifying the Startup script itself, you can place a Startup.sh file into the CommuniGate Pro base directory. Startup scripts check if that file exists, and execute it before performing the requested start/stop operations.

Customizing OpenVMS Startup Procedures

You may need to add certain DCL commands to the CommuniGate Startup procedure. Since the Startup procedure is a part of CommuniGate Pro application software, it is overwritten every time you upgrade your CommuniGate Pro system. Instead of modifying the Startup procedure itself, you can place a STARTUP.COM file into the CommuniGate Pro base directory. Startup procedure checks if that file exists, and it executes that file before starting the Server.

Shutting Down

The CommuniGate Pro Server can be shut down by sending it a SIGTERM or a SIGINT signal.

On Unix and OpenVMS platforms you can use the startup script with the stop parameter, or you can get the Server process id from the ProcessID file in the base directory and use the kill command to stop the server. On OpenVMS platforms the KILL.EXE program can be found in the application directory.

On the Windows NT platform, you can use the Services control panel to stop and start the CommuniGate Pro server.

You can also use the shutdown CLI API command to stop the server.

When the Server receives a shutdown request, it closes all the connections, commits or rolls back mailbox modifications, and performs other shutdown tasks. Usually these tasks take 5-15 seconds, but sometimes (depending on the OS network subsystem) they can take more time. Always allow the Server to shut down completely, and do not interrupt the shutdown process.

OS syslog

The CommuniGate Pro server can store as much as several megabytes of Log data per minute (depending on the Log Level settings of its modules and components), and it can search and selectively retrieve records from the log. To provide the required speed and functionality, the Server maintains its own multithreaded Log system.

The Server places records into the OS log:

• when it starts up;
• when it shuts down;
• when it detects its own memory leaks;
• when it detects its own program error;
• when a program error exception (signal) is raised.

The system Log is:

• system.log or mail.log file on Unix systems
• Event Log on Windows systems

Server Root Privilege

The CommuniGate Pro is designed as a highly secure application. In order to perform certain operations, the Server runs as root on Unix platforms, and it carefully checks that no user can access restricted OS resources via the Server. Since many other servers do not provide the same level of security, system administrators preferred to run servers in a non-root mode, so a hole in the server security would not allow an intruder to access the restricted OS resources.

CommuniGate Pro can "drop" the root privilege. The privilege can be dropped in the "permanent" or "reversible" mode. When asked to drop the root (uid=0) privilege, the Server changes its UID:

• to the UID of the Unix user cgatepro (if exists), otherwise
• to the UID of the Unix user nobody (if exists), otherwise
• to the UID 1

When the root privilege is dropped, the following restrictions apply:

• No Listener port with number < 1024 can be opened. If you try to add a listener with the port number n (n < 1024), the port with the number 8000+n is opened instead.
• Remote applications started via Account-Level Rule EXECUTE command run in the current CommuniGate Pro Server environment (the effective UID and other OS-level process parameters are not changed).
• OS Passwords cannot be used.

If the root privilege was dropped in the "reversible" mode, the root privilege can be restored. For example, if you need to open a listener on the port 576, but the Server root privilege has been dropped, you should restore the root privilege first, then open the listener port, and then you can drop the Root privilege again.

To drop the root privilege permanently, use a special Command Line Option.

To drop the root privilege in the "reversible" mode, click the "Drop Root" button on the General page. The button should change to the "Restore Root" button - you can use it to restore the Server root privilege. This option is not available on those platforms that cannot drop the root privilege correctly (Linux).

Domain Administration

If your Server has several Secondary Domains, you may want to grant some user in those domains the domain administrator access right.

A domain administrator can use the WebAdmin interface to access the pages in the Domains section, but the access is limited to that Domain only, and not all Domain and Account Settings can be modified.

When you grant the domain administrator access right to a user, you will see a list of specific access rights - the internal names of Domain and Account Settings. You should specify which settings the domain administrator can modify. Also, the list of enabling options allows you to grant the domain administrator rights:

• to create, rename, and remove Accounts
• to create, rename, and remove account aliases
• to create, rename, and remove Groups and Forwarders
• to create, rename, and remove mailing lists
• to modify the WebUser Interface files (HTML templates and graphic images)
• to send Alert messages to domain users
• to administer other domains
• to have full direct access to all Mailboxes in all domain Accounts.
• to have full direct access to all Personal Web Sites in all domain Accounts.
• to have full direct access to all Mailing Lists in all domain Accounts.

The domain administrator access right can be granted to users in secondary domains by a system administrator that has the Accounts (All Domains and Account Settings) access right.

A Domain administrator can control the domain using the same WebAdmin port (see HTTP module description for the details), or using the Command Line Interface commands.

Domains Administrators in other Domains

When a customer has several Domains, you may want to let an Account in one Domain administer other Domains. You should grant such an Account the CanAdminSubDomains Domain Admin right. Then you should open the Domain Settings page for the target Domain and specify the administrator Domain name in the Administrator Domain Name field.

Sample.

A customer has the company1.com, company2.com, company3.dom Domains on your Server. You may want to specify "company1.com" as the Admininstrator Domain Name in the company2.com and company3.com Domain Settings. Now, any Account in the company1.com Domain that has the CanAdminSubDomains Domain Administrator right can administer all three Domains.

Note: when a Domain Administrator connects to the Domain WebAdmin Interface, the browser displays the Login Dialog Box. If the Administrator Account is in a different Domain, the full account name (accountName@domainName) should be specified.

WebAdmin Preferences

Server and Domain administrators can customize the WebAdmin Interface parameters, including the initial number of Accounts to be displayed in the Account Lists, the refresh rate for the Monitor pages, etc. The Preferences also specify the character set used for WebAdmin pages. If you plan to use non-ASCII symbols, specify the correct character set first.

Each CommuniGate Pro WebAdmin realm has its own WebAdmin Preferences page. Click the icon on any of the WebAdmin pages to open the Preferences page.

The specified Preferences are stored as one of the Administrator Account Setting attributes, so different administrators can have different Preferences.

Customizing Domain WebAdmin Interface

The Server Administrator can modify the look and feel of the Domain WebAdmin interface. For each CommuniGate Pro Domain, a custom version of WebAdmin files can be created and uploaded to the Domain storage.

To modify the Domain WebAdmin Interface pages, connect to the server WebAdmin Interface as a Server Administrator, open the Domain Settings page and click the WebAdmin link. The list of WebAdmin files will appear. Click the Accounts link to open the subdirectory containing the files used to compose WebAdmin pages in the "Account" realm:

(Accounts subdirectory) UP

Marker File Name Size Modified default AccountDefaults.html 1929 15-Feb-02 default AccountList.html 2K 15-Feb-02 AccountMain.html 4K 27-Feb-02 default AccountRemove.html 489 15-Feb-02 default AccountRights.html 2K 15-Feb-02 default AccountSettings.html 2K 15-Feb-02 .................................. default WebUserSettings.html 1194 15-Feb-02 default WebUserSettingsMain.html 3K 15-Feb-02 Totals: 32 66K

If the file exists in the Domain WebAdmin storage, its name is marked with a check box in the Marker field. You can select the check box and click the Delete Marked button to remove the custom file(s) and make the Server use the default WebAdmin files.

The Server Administrator can also upload custom files to the "default" WebAdmin storage. Those files will be used in all Domain WebAdmin Interfaces unless a Domain has the same file explicitly uploaded into its WebAdmin Interface storage.

To upload the "default" WebAdmin files, use the Server WebAdmin Interface as a Server Administrator, and open the WebAdmin link on the Domains page. If your server is a member of a Cluster, an additional panel appears. This panel allows you to upload files either as the default Domain WebAdmin files for all non-shared (this-server-only), or for all shared (cluster-wide) Domains.

If the file does not exist in the Domain WebAdmin storage, the default file (server-wide or cluster-wide, depending on the Domain type) is used. If this file does not exist, the file from the application directory WebAdmin subdirectory is used.

To modify some element of the WebAdmin Interface:

• use the WebAdmin Interface Editor to open the directory that contains the file you want to modify;
• use the file link to open the file and/or to copy the file on your local disk;
• modify the file using any HTML editor program;
• on the same WebAdmin Interface Editor directory page, click the Browser button and select the modified file on your local disk;
• click the Upload File button to upload the modified file to the CommuniGate Pro WebAdmin directory opened in the WebAdmin Interface Editor.

If the WebAdmin directory/subdirectory did not contain a custom copy of the uploaded file, you will see the default file marker changing to a checkbox. If a custom version of that file already existed in the WebAdmin directory/subdirectory, the old version is replaced with the uploaded one.

To remove a custom version of a WebAdmin Interface file, select the checkbox on the left of that file name and click the Delete Marked button. If the file with that name exists in the default WebAdmin subdirectory or in the application directory WebAdmin subdirectory, the file name does not disappear from the WebAdmin Interface Editor page, but the name gets the default marker indicating that the default (or "stock") version of the file will be used again.

Note:The Server WebAdmin interface always uses the files located in the WebAdmin subdirectory of the application directory. If you modify the WebAdmin interface for the main domain, the modified pages will be used when a Domain Administrator of the main domain uses the WebAdmin Interface. The Server Administrator will see the framed version of the WebAdmin Interface (with the Settings, Domains, Directory, and Monitors realms) and the "stock" WebAdmin files will be used to compose the Server WebAdmin Interface pages.

Customizing Server Prompts

The Server Administrator can modify the protocol prompts and other text strings the CommuniGate Pro Server sends to client mailers.

To modify the Server Strings, the administrator should follow the Strings link on the General Settings page. The Server Strings page appears (the actual page has much more strings):

Keyword String POPPrompt CommuniGate Pro POP3 Server ^0 ready SMTPByeBye CommuniGate Pro SMTP closing connection SMTPNoRelay we do not relay SMTPNonInternet will leave the Internet SMTPNormalPrompt ^1 ESMTP CommuniGate Pro ^0

To modify a Server String, enter the new text in the text field, and select the upper radio button. To change the string to its default value (displayed under the text field), simply select the lower radio button.

Click the Update button to update the Server Strings.

Domain Name Resolver (DNR)

The CommuniGate Pro server uses its own high-speed multithreaded Domain Name Resolver to convert domain names into network (IP) addresses. To convert names, the Domain Name Resolver sends requests to the specified Domain Name Servers.

Server Administrators with the Can Modify Settings access right can modify the Resolver settings. Open the Obscure page in the Settings section of the Server WebAdmin Interface:

Domain Name Resolver

Log: Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info Concurrent Requests: 13510152550100250300other Initial Time-out: 1 second2 second3 second5 seconds7 seconds10 seconds15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes Retry Limit: 134567891015202550100other DNS Addresses: OS-specifiedCustom [209.1.58.247], [206.40.74.1] Dummy IP Addresses: 64.94.110.11 ; *.com, *.net "wildcard"

Log

Use this setting to specify what kind of information the Domain Name Resolver should put in the Server Log. Usually you should use the Major or Problems levels. In the later case you will see the information about all failed DNS lookups. If you use the RBL services, you may see a lot of failed lookups in the Log. When you experience problems with the Domain Name Resolver, you may want to set the Log Level setting to Low-Level or All Info: in this case protocol-level or link-level details will be recorded in the System Log as well.

The Resolver records in the System Log are marked with the DNR tag.

Concurrent Requests

This setting limits the number of concurrent requests the Resolver can send to Domain Name Servers. On a heavily-loaded mail relay processing several hundred requests per second, this parameter should be selected after some testing: older DNS servers may crash if requested to process too many concurrent requests, also in certain cases the DNR traffic may start to compete with the mail transfer (SMTP) traffic.

Initial Time-out

Then Domain Name System uses a connectionless UDP protocol, and if there any network trouble, a UDP request or reposnse can be lost (TCP protocol automatically resends lost packets). The Domain Name Resolver waits for a response from a DNS server for the period of time specified with this option.

If a response is not received, the Resolver resends the request, and waits twice longer, if it times out again, it can resend the request again and wait three times longer.

If you have several Domain Name Servers specified, each time the resolver needs to repeat a request, it sends it to the next DNS server in the list.

Retry Limit

This option specifies how many time the Resolver should re-send the same request if it has not received any response from a DNS server.

Note: when a request is an RBL request, the Resolvers sends the same request not more than twice, and both times it uses the same (Initial) response time-out.

DNS Addresses

This setting specifies how the CommuniGate Pro Server selects the DNS servers to use. If the OS-specified option is selected, the Server reads the DNS server addresses from the OS. To force the server to re-read those addresses, click the Refresh buttom on the General page in the Settings section.

If the Custom option is selected, the CommuniGate Pro server will use the DNS servers addresses listed in the text field next to this pop-up menu.

If no DNS server address is specified, the CommuniGate Pro server uses the 127.0.0.1 address, trying to connect to a DNS server that can be running on the same computer as the CommuniGate Pro server.

Dummy IP Addresses

This setting allows you to specify network (IP) addresses and/or address ranges that should be considered as "non-existent". Some DNS authorities may choose to "map" all non-existant names within their domains to some special IP address(es).

When a domain name is resolved into IP addresses, the Resolver checks the first address. If this address is listed in the Dummy IP Addresses list, the Resolver returns the "unknown host/domain name" error code.

The Domain Name Resolver uses TCP connections if the server UDP response came back with the "Truncated" flag set. This feature allows the Resolver to retrieve very large records from DNS servers.

Network Address Lists

Many CommuniGate Pro components use lists of Network (IP) Addresses. These lists are used to specify Client and Blacklisted addresses, to specify access restrictions for Listeners, etc. This section describes the format used to specify Network Address Lists.

10.10.12.24 ; our back-up 10.10.13.32-10.10.13.191 ; our dial-ups !10.10.13.100-10.10.13.102 ; excluded addresses ; a comment line 206.253.23.169 ; our other office

A Network Address List is specified as multi-line text data.

Each line should include either one IP address or an address range - two IP addresses separated with the minus sign: a range includes both IP addresses and all addresses between them.

The first IP address can be preceded with the exclamation point ! sign. In this case the specified address or the address range is excluded from the list composed using the preceding lines.

A comment (separated with the semicolon (;) symbol) the can be placed at the end of a line. A line starting with a semicolon symbol is a comment line.

External Helper Programs

The CommuniGate Pro Server can use external programs to implement various operations - message scanning, user authentication, RADIUS login policies, etc. All these external programs are handled in the same way, and should support the simple Helper Interface.

To specify the External Helper program path and other parameters, open the General page in the Settings realm of the WebAdmin Interface and click the Helpers link:

Helper Name
Log: Crashes OnlyFailuresMajor & FailuresProblemsLow LevelAll Info Program Path: Time-out: disabled15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour Auto-Restart: disabled5 seconds7 seconds10 seconds15 seconds30 secondsminute2 minutes3 minutes5 minutes10 minutes15 minutes30 minuteshour2 hours3 hours6 hours

The checkbox next to the Helper name tells the Server to start the specified program as a separate OS process.

Log

Use this setting to specify the type of information the Helper support module should put in the Server Log. Each Helper uses its own tag for its Log record.

Program Path

The file name (path) of the Helper program. If a relative path is specified, it shoud be relative to the CommuniGate Pro base directory.

Time-out

If the Helper program does not send a response within the specified period of time, the program is stopped.

Auto-Restart

If the Helper program stops, and this option is disabled, all pending requests are rejected. If the Helper program stops when this option is enabled, the Server waits for the specified period of time, restarts the Helper Program and re-sends the requests to it.

External Helper protocol

When the Helper program is running, the Server sends commands to the Helper process via the process standard input. The Server reads responses from the process standard output.

Commands and responses are text lines, ending with the EOL symbol(s) used in the Server OS.

Each command starts with a sequence number, and the response produced with the Helper program starts with the same number. This method allows the Helper program to process several requests simultaneously, and it can return responses in any order.

The Helper program can send information responses at any time. An information response starts with the asterisk (*) symbol. The Server ignores information responses, but they can be seen in the Server Log.

The response lines generated with a Helper program should not be larger than 4096 bytes.

Note: communication between the Server and an Helper program takes place via OS pipes, and many programming libraries buffer output data sent to pipes. Check that your Helper program uses some form of the flush command after it sends a response to its standard output, otherwise the response will not reach the Server.

Helper programs are started with the CommuniGatePro base directory as their current directory.

Helper programs should not write anything to their standard error streams, unless they want to report a reason for the failure before quitting. CommuniGate Pro reads the program standard error stream only after the program has terminated, and if the program writes into that stream while processing Server commands, the program will be suspended by the OS when the standard error pipe buffer is full.

The Interface Version command is used to provide compatibility between different versions of Helper programs and different versions of the CommuniGate Pro Server. The Server sends this command specifying the protocol version it implements:
nnnnnn INTF serverInterfaceVersion
where:

nnnnnn

a unique sequence number for this request

serverInterfaceVersion

the version of the Helper protocol implemented by this version of the CommuniGate Pro Server.

The Helper program should return the INTF response and the supported protocol version.
nnnnnn INTF programInterfaceVersion
If the returned number is smaller than the Server protocol version, the Server will use this (older) protocol version.

When the Server shuts down or when it needs to stop the Helper program, it sends the QUIT command, and then closes the process standard input. The Helper program should send the OK response and it should quit within 5 seconds.

Sample session (I: - server commands sent to the program standard input, O: - responses the program writes to its standard output, COMMAND - a Helper-specific command):

O: * My Helper program started
I: 00001 INTF 1
O: 00001 INTF 1
I: 00002 COMMAND parameters
O: 00002 OK
I: 00003 COMMAND parameters
I: 00004 COMMAND parameters
O: * processing 00003 will take some time
O: 00004 ERROR description
O: 00003 OK
I: 00005 QUIT
O: * processed: 5 requests. Quitting.
O: 00005 OK
I: stdin closed

The sample above shows that the Server does not wait for a response before it sends the next command, and that it can accept responses for several pending commands in any order - as long as each command receives a response within the specified time limit.