10
Managing Protocol Server Processes

The protocol server processes transfer e-mail from the eMail Server database to the user's e-mail client or browser. When you install a node or protocol server tier, you can run the Configuration Assistant to set up the initial configuration. If you do not want to use the Configuration Assistant, then you can use the following procedures discussed in this chapter to modify the configuration manually:

• Configuring the Protocol Server Database Connections

• Specifying Gateways for the Protocol Servers

• Configuring Protocol Servers for SSL

• Obtaining an SSL Trusted Certificate

Configuring the Protocol Server Database Connections

To use the protocol server processes, you must configure the number of Net8 connections between each registered protocol server process and the database. To do this, you must edit the protocol server configuration files manually. There are separate configuration files for POP3 and IMAP4 protocol servers. These configuration files are created during the installation using default parameters.

Steps for Configuring the Protocol Server Database Connections

This task can be done either automatically by using the Configuration Assistant, or manually by using a text editor. For instructions on how to use the Configuration Assistant, refer to the Oracle eMail Server Installation Guide.

1. Use any text editor to open the configuration file that you want to update on the machine where the protocol servers are installed.

   The name of the configuration file is specified with the confm parameter in the protocol server process parameters. The default file names are:

   $ORACLE_HOME/office/config/node_sid/iosps23.cfg for the POP3SRV process

   $ORACLE_HOME/office/config/node_sid/iosps27.cfg for the IMAP4SRV process

   See Also: "SPS Process Parameters (Common to both IMAP4 and POP3)" for more information about the confm parameter

2. Add the following line at the bottom of the configuration file to configure the Net8 connections:

   <connect_string> <minimum_connections> <maximum_connections> <increment> 
   <timeout> <domain>
   

   See Also: "Variables for Configuring the Protocol Server Database Connections" for more information about the parameters in this file

3. If you want to use different parameters for different registered protocol server processes (for example, because one instance of a protocol server uses more database connections than the other), you can create more than one configuration file and change the confm process parameter for that registered protocol server process instance.

   See Also: "SPS Process Parameters (Common to both IMAP4 and POP3)" for more information about the confm parameter "Setting a Parameter for a Registered Process" for more instructions on changing a parameter

Variables for Configuring the Protocol Server Database Connections

Variable	Description
connect_string	Connect string used to access database.
increment	Number of new database connections to start when the existing connections are all used. For example, an increment of 3 means that three new connections will be started each time the server needs additional connections. New connections cannot exceed the number specified for the maximum_connections parameter.
maximum_connections	Maximum number of Net8 connections from the protocol server to the database. On Solaris, the value for this parameter plus the maxclt parameter in the IMAP4SRV/POP3SRV process parameters should be less than 1000. See Also:: "SPS Process Parameters (Common to both IMAP4 and POP3)" for more information about the maxclt parameter
minimum_connections	Minimum number of Net8 connections from the protocol server to the database.
timeout	Amount of time (in seconds) to wait before releasing a connection that is not being used.
domain	Used as the users home node for that domain. This enables the IMAP server to service multiple domains.

Example of Configuring the Protocol Server Database Connections

The following example shows a file with a line added at the bottom using the SFNode1 connect string with a minimum of 10 connections, maximum of 100 connections, increments of 2 new connections at a time, and a timeout after 120 seconds (this information appears in the last line of the file displayed in bold):

# This is the default configuration file for SPS connect strings. 
# Line started with "#" is comment. 
# Spaces and tabs are used as delimiters between fields in a line. 
# Parameters for one connect string have to be in the same line. 
# The format of parameters of a connect string is: 
# connect_string  minimum_connections maximum_connections increment timeout 
# For example: 
# im-sun.world  10 100 5 100 
# Add real connect strings and their parameters after this. 
SFNode1 10 100 2 120

Specifying Gateways for the Protocol Servers

You must specify the gateways that are registered in the system so that the protocol server processes know how to forward messages. You must add the gateway information to a configuration file that is created during the installation process.

Steps for Specifying Gateways for the Protocol Servers

This task can be done either automatically by using the Configuration Assistant, or manually by using a text editor. For instructions on how to use the Configuration Assistant, refer to the Oracle eMail Server Installation Guide.

1. Use any text editor to open the $ORACLE_HOME/office/config/node_sid/imapd.cfg file on the node where the protocol servers are installed.

2. At the bottom of the file, add a new line with the following parameters using the format shown in the file comments:

   unixgwy=<gateway_name>
   unixgwy=<gateway_name>
   

   See Also: "Parameters for Specifying Gateways for the Protocol Servers" for more information about the parameters available for this file

Parameters for Specifying Gateways for the Protocol Servers

Parameter	Description
unixgwy	Gateway name to strip from message header addresses. You can repeat this entry as many times as needed for all your gateways.

Configuring Protocol Servers for SSL

If you configure protocol server process for SSL encryption, all messages transferred from the server to the client will be encrypted.

Steps for Configuring Protocol Servers for SSL

This task can be done either automatically by using the Configuration Assistant, or manually by using the Administration Tool GUI or the OOMGR command-line interface. For instructions on how to use the Configuration Assistant, refer to the Oracle eMail Server Installation Guide.

1. Determine whether you will support only SSL messages, or both SSL and non-SSL messages.
   • If you decide to support SSL only, you can configure your existing protocol server processes to be dedicated to SSL. Go to the next check box.

   • If you decide to support both SSL and non-SSL, then you should leave the existing protocol server processes for non-SSL and register one new POP3SRV process and one IMAP4SRV process to be dedicated to SSL. Refer to "Registering a New Process" for instructions.

2. To dedicate the protocol server processes and listener process to SSL, configure the following parameter value for each instance of the IMAP4SRV, POP3SRV, and IOLISTENER processes that you want to handle SSL-encrypted messages:

   Parameter	Value
   flags	Enter 64 to set the SSL bit.See Also:: "IMAP4SRV Process Parameters (IMAP4-Specific)" or "POP3SRV Process Parameters (POP3-Specific)" for more information about the flags parameter

   Refer to "Setting a Parameter for a Registered Process" for instructions.

3. Refresh the IOLISTENER process so that it starts using the new settings. Refer to "Refreshing a Process" for instructions.

Obtaining an SSL Trusted Certificate

Before you can begin sending messages encrypted in SSL, you must use the eMail Server Wallet Manager to generate a public/private key pair and then obtain a trusted certificate. To obtain the certificate, you must send a certificate request file to a Certification Authority. When you receive the certificate, you must store it with the private key in the database. Once this is done, any SSL-enabled client can send and receive secure messages from the certified server.

Steps for Obtaining an SSL Trusted Certificate

This task can be done either automatically by using the Configuration Assistant, or manually by using a text editor and a shell tool. For instructions on how to use the Configuration Assistant, refer to the Oracle eMail Server Installation Guide.

1. Use any text editor to create a certificate request information file named $ORACLE_HOME/office/admin/reqinfo.txt.

   Note: You must have a separate certificate for each host machine with protocol server processes, but you may use the same certificate for all protocol server processes on the same machine (both POP3 and IMAP4).

2. In the certificate request information file that you created, enter the following specific information about your site:

   Common-Name:	Your Internet domain name.
   Organization:	Your company name.
   Organization Unit:	Your organization within your company.
   Country:	Country in which your company resides.
   State:	U.S. state in which your company resides. If you are outside the U.S., enter the appropriate country code.
   Webmaster:	Your name, or the name of the person who should be contacted regarding the certificate.
   Phone:	Phone number of the person listed as Webmaster.

   The Wallet Manager uses the information in this file to generate a certificate request file later.

Figure 10-1 Sample reqinfo.txt File

Common-Name: acme.com Organization: Acme Corp. Organization Unit: eMail Server Country: US State: California Webmaster: C Kent <[e-mail]> Phone: [phone]

Run the Wallet Manager to generate the public/private key pair and the certificate request file.

Enter the following command at the shell prompt:

$ORACLE_HOME/bin/mhzwalletmgr -gc

Respond to the prompts the Wallet Manager displays:

Oracle eMail Server Wallet Manager Version 4.3 Production
Please input certificate password:
Please input the password again:
Wallet manager finished successfully

Note: The certificate password is used to encrypt the private key file.

The Wallet Manager generates two files:

• Private key that has been encrypted and then encoded with the password requested by the Wallet Manager. This file is called $ORACLE_HOME/office/admin/pvtkey.txt

• Certificate request file that you send to the Certification Authority to obtain the trusted certificate. This file is called $ORACLE_HOME/office/admin/certreq.txt

Figure 10-2 Sample certreq.txt File

Webmaster: C Kent <[e-mail]> Phone: [phone] Server: Oracle Corporation Certificate Request Utility 4.3 Common-name: acme.com [Hostname for server where POP3/IMAP4 are running] Organization Unit: eMail Server Organization: Acme Corp. State: California Country: US -----BEGIN NEW CERTIFICATE REQUEST----- MIIBaDCB8wIBADBuMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEV MBMGA1UEChQMT3JhY2xlIENvcnAuMRQwEgYDVQQLFAtJbnRlck9mZmljZTEdMBsG A1UEAxQUd2luZHVwLnVzLm9yYWNsZS5jb20wfDANBgkqhkiG9w0BAQEFAANrADBo AmEAwAfsuKOQgPFY6gLuB0rNbhdBfMiL5Reyx+qwFLllbkzxDdLrOrqEOfri7kk2 YT0ugVR1QrNhyekPVVa0GkB+QYMdPgiXYSwzJjdMGUxdshrrhIdSXufaIJQeCIvK MnCjAgMBAAGgADANBgkqhkiG9w0BAQQFAANhAJC5hNuC7LCzlH91M1+qalXltjus sduMBKFxB14+y!MgX07L3HM6GNIeP2E/z17xDU4ygSZF5Cwsy5Bcb6I94m/Gora+7 6gF7mRq+Z1e6EoENtC+RK2v7LPjm+ZhPzW5i5g== -----END NEW CERTIFICATE REQUEST-----

Figure 10-3 Sample pvtkey.txt File

-----BEGIN ENCRYPTED PRIVATE KEY----- MIICCDAaBgkqhkiG9w0BBQMwDQQIHCqcuR+NQCACAQUEggHonUln5gOWliN70kXC 5PY+W9IM/6foeGYvlbe1T/IKroJpcSqmPF1tSZVnMWDTJN7wCU4530ZiEEoQEkrF Iur4tXAEYsv9M/MYmD0TYUBR2tQIXVFr/dVs0MfF2Yz649XtMgIDQ8sTImnP1jjs P/Emx+hJk+PCMl5wYQGeNgT1yYVexdsrAOkdS2TLFT6XkkoB7+2E5pFSHfqeAGqj gDKYQ8dFBlWZmqY18gkqKjVwjEovv+iT3/rPmheVM822JYgK9Qsi5r/Z4IONZaAZ K/s4a7heQUa5hqLJsguIevM5x32oGsKFS5f77pj3SD2uX5p9fRJ7Yf1LKLVawN0P AZs4SsPpG9n3IrEkwFhaCQHj+2xjm7YvafpRftPnHa68Hlb6JephPEkWUdTfWtic tCOiyAMuOJpwLBEMjCwdfRyDKfN3uX+w/wJzikT5Aug2ZxdSVEyEgexhvtNDFHMv CBgKggLrvy+sl0eD0KFO9n3QcgChOKjwEMnRUhCeAqmO1UkE9cUHdDbWhAsOs/7M C+j/vbs2cl98eUdYOyQO6273GB0ERTFrCPuprsM1jviu2M+tpGtNOfnvkAf09L40 3o3EM7h1LYhBCzEW+xnLT88Lw3eernLNl9NgfE+E5NRlCsfG0ZaSokyF+IA= -----END ENCRYPTED PRIVATE KEY-----

Send the certreq.txt file to the Certificate Authority of your choice to obtain a trusted certificate. Each Certificate Authority has a different procedure for obtaining a trusted certificate. For example, you can go to the VeriSign, Inc. Web site at

http://digitalid.verisign.com/

and request a trial Server ID (trusted certificate) that you can use to test your system. To obtain your trusted certificate, follow the instructions provided by your Certificate Authority.

Figure 10-4 Sample Trusted Certificate

-----BEGIN CERTIFICATE----- MIICMTCCAdsCEA3fXhQyL7meioPDZLUco/4wDQYJKoZIhvcNAQEEBQAwgakxFjAU BgNVBAoTDVZlcmlTaWduLCBJbmMxRzBFBgNVBAsTPnd3dy52ZXJpc2lnbi5jb20v cmVwb3NpdG9yeS9UZXN0Q1BTIEluY29ycC4gQnkgUmVmLiBMaWFiLiBMVEQuMUYw RAYDVQQLEz1Gb3IgVmVyaVNpZ24gYXV0aG9yaXplZCB0ZXN0aW5nIG9ubHkuIE5v IGFzc3VyYW5jZXMgKEMpVlMxOTk3MB4XDTk4MDUyOTAwMDAwMFoXDTk4MDYxMjIz NTk1!OVowbjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFTATBgNV BAoUDE9yYWNsZSBDb3JwLjEUMBIGA1UECxQLSW50ZXJPZmZpY2UxHTAbBgNVBAMU FHdpbmR1cC51cy5vcmFjbGUuY29tMHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAMi1 Yz56AT4jwZ3kCzoVK11XIHysugMKmrj2NG7mkpCwC1VDYiMgHB8c9Q1bdi7yVygs hB/NSR2kMGJzZVHUQIoblUC2b5T36S7irlpVUrigm0VpWiR5LRly0ToayIJ4TwID AQABMA0GCSqGSIb3DQEBBAUAA0EAVu/Jk8o5k2Ms6luFIIGR/KMmRaXWU8PxCZi+ 99oZCjd1fjJdCTyzivHlxXK8sfYUnS8O2hXqgRQ10lfzuZIz6A== -----END CERTIFICATE-----

Copy and paste the following items into the wallet file, $ORACLE_HOME/office/admin/sslcerts.txt:

• Private key from the pvtkey.txt file (including the BEGIN PRIVATE KEY and END PRIVATE KEY lines)

• Trusted certificate from the certificate authority message (including the BEGIN CERTIFICATE and END CERTIFICATE lines)

Figure 10-5 Sample sslcerts.txt File

-----BEGIN ENCRYPTED PRIVATE KEY----- MIICCDAaBgkqhkiG9w0BBQMwDQQIHCqcuR+NQCACAQUEggHonUln5gOWliN70kXC 5PY+W9IM/6foeGYvlbe1T/IKroJpcSqmPF1tSZVnMWDTJN7wCU4530ZiEEoQEkrF Iur4tXAEYsv9M/MYmD0TYUBR2tQIXVFr/dVs0MfF2Yz649XtMgIDQ8sTImnP1jjs P/Emx+hJk+PCMl5wYQGeNgT1yYVexdsrAOkdS2TLFT6XkkoB7+2E5pFSHfqeAGqj gDKYQ8dFBlWZmqY18gkqKjVwjEovv+iT3/rPmheVM822JYgK9Qsi5r/Z4IONZaAZ K/s4a7heQUa5hqLJsguIevM5x32oGsKFS5f77pj3SD2uX5p9fRJ7Yf1LKLVawN0P AZs4SsPpG9n3IrEkwFhaCQHj+2xjm7YvafpRftPnHa68Hlb6JephPEkWUdTfWtic tCOiyAMuOJpwLBEMjCwdfRyDKfN3uX+w/wJzikT5Aug2ZxdSVEyEgexhvtNDFHMv CBgKggLrvy+sl0eD0KFO9n3QcgChOKjwEMnRUhCeAqmO1UkE9cUHdDbWhAsOs/7M C+j/vbs2cl98eUdYOyQO6273GB0ERTFrCPuprsM1jviu2M+tpGtNOfnvkAf09L40 3o3EM7h1LYhBCzEW+xnLT88Lw3eernLNl9NgfE+E5NRlCsfG0ZaSokyF+IA= -----END ENCRYPTED PRIVATE KEY----- -----BEGIN CERTIFICATE----- MIICMTCCAdsCEA3fXhQyL7meioPDZLUco/4wDQYJKoZIhvcNAQEEBQAwgakxFjAU BgNVBAoTDVZlcmlTaWduLCBJbmMxRzBFBgNVBAsTPnd3dy52ZXJpc2lnbi5jb20v cmVwb3NpdG9yeS9UZXN0Q1BTIEluY29ycC4gQnkgUmVmLiBMaWFiLiBMVEQuMUYw RAYDVQQLEz1Gb3IgVmVyaVNpZ24gYXV0aG9yaXplZCB0ZXN0aW5nIG9ubHkuIE5v IGFzc3VyYW5jZXMgKEMpVlMxOTk3MB4XDTk4MDUyOTAwMDAwMFoXDTk4MDYxMjIz NTk1!OVowbjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFTATBgNV BAoUDE9yYWNsZSBDb3JwLjEUMBIGA1UECxQLSW50ZXJPZmZpY2UxHTAbBgNVBAMU FHdpbmR1cC51cy5vcmFjbGUuY29tMHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAMi1 Yz56AT4jwZ3kCzoVK11XIHysugMKmrj2NG7mkpCwC1VDYiMgHB8c9Q1bdi7yVygs hB/NSR2kMGJzZVHUQIoblUC2b5T36S7irlpVUrigm0VpWiR5LRly0ToayIJ4TwID AQABMA0GCSqGSIb3DQEBBAUAA0EAVu/Jk8o5k2Ms6luFIIGR/KMmRaXWU8PxCZi+ 99oZCjd1fjJdCTyzivHlxXK8sfYUnS8O2hXqgRQ10lfzuZIz6A== -----END CERTIFICATE-----

For security purposes, you should store the contents of the sslcerts.txt file in the database. To do this, you must run the Wallet Manager again. (If you do not want to store the contents of the sslcerts.txt file in the database, go to step 8.)

Enter one of the following commands at the shell prompt:

To perform this task:	Use this command:
Store a certificate for a POP3 protocol server only	$ORACLE_HOME/bin/mhzwalletmgr -sc POP3SRV <connect_string> <filename>
Store a certificate for a IMAP4 protocol server only	$ORACLE_HOME/bin/mhzwalletmgr -sc IMAP4SRV <connect_string> <filename>
Store a certificate for both IMAP4 and POP3 protocol servers	$ORACLE_HOME/bin/mhzwalletmgr -sc POP3SRV IMAP4SRV <connect_string> <filename>

Parameter	Description
connect_string	Connect string used to access database. See Also:: "Configuring the Protocol Server Database Connections" for more information.
filename	$ORACLE_HOME/office/admin/sslcerts.txt

The Wallet Manager will prompt you for the eMail Server ADMIN user password and for the password used to encrypt the private key (the private key password was specified in step 4).

After storing the sslcerts.txt file in the database, the Wallet Manager will rewrite the file located in $ORACLE_HOME/office/admin to be empty. This will destroy the unprotected versions of the private key and trusted certificate for added security.

If you do not want to store the contents of the sslcerts.txt file in the database, complete the following tasks:

• Verify that the certificate parameter for the POP3SRV and IMAP4SRV processes refers to the sslcerts.txt text file that you created in step 6.

• Run the Wallet Manager to set the password used to encrypt the private key so that the POP3 and IMAP4 protocol server processes can read the private key data. Enter the following command at the shell prompt:

  $ $ORACLE_HOME/bin/mhzwalletmgr -sp [POP3 | IMAP4] <connect_string>
  

  See Also: "SPS Process Parameters (Common to both IMAP4 and POP3)" for more information about the certificate parameter