How To Configure the SMTP Client To Use SMTP Authentication with a SMTP Relay

Problem

This document discusses how to configure the IBM i SMTP Client to use SMTP Authentication and SSL/TLS when connecting to a SMTP Relay.

Environment

IBM i OS

Resolving The Problem

For more information on configuring the IBM i SMTP Client to relay email to Microsoft Office 365 or Google Mail (Gmail), refer to the IBM Technical document, "Configuration of the IBM i SMTP Client to Relay Email to Office365 and Gmail".

===================================
General SMTP authentication & TLS configuration instructions for the IBM i SMTP Client.

Prerequisites

In order to configure the IBM i SMTP Client for SMTP Authentication and SSL/TLS, the following prerequisites must exist. This document assumes the following:

- The IBM Digital Certificate Manager (DCM) *SYSTEM Certificate Store already exists
- The DCM Local certificate authority (CA) Certificate Store already exists

The following documents can help configure these items if they are not already configured:

How to create the *SYSTEM store in DCM
How to Create the Local Certificate Authority (CA) Store in DCM

Additional Notes:

If you would like to configure SSL/TLS between the IBM i and a remote mail relay WITHOUT providing authentication credentials, refer to the following documentation.

Configuring SSL Between IBM i and Remote Mail Router WITHOUT Authentication

===================================

1)

Obtain the certificate authority (CA) certificates used by the SMTP Relay server you are connecting to.

Since SMTP Authentication on the IBM i OS requires a SSL/TLS encrypted connection, you will need to obtain the certificate authority (CA) certificates used by your SMTP Relay Server for SSL/TLS connections. You can either obtain these manually from your SMTP Relay Server administrator or use the QMGTOOLS GETSSL utility if you know the TCP/IP hostname or IP address of the SMTP Relay Server and the SSL/TLS port it listens on. For instructions on how to use the QMGTOOLS GETSSL utility, please refer to the following document.

QMGTOOLS GETSSL Utility

Example:
QMGTOOLS/GETSSL IP(MYDOMAIN.OUTLOOK.COM) PORT(587) STRTLS(Y) SERVICE(SMTP)

The SSL/TLS certificates will be placed in the /tmp directory with the nomenclature, <user>_sslchainXX.cer, where XX is the order number of the certificate. This is important since it helps you identify which CA certificate should be imported first, second, etc. into DCM.

i.e. /tmp/QSECOFR-sslchain01.cer

2)

Import your SMTP Relay CA certificates into DCM.

a)	In a web browser, execute the following URL to access the Digital Certificate Manager (DCM) application: http://systemname:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0 (Replace *systemname* with the TCP/IP hostname or IP address of your IBM i server)
b)	Click the "Select a Certificate Store" button.
c)	Select the radio button next to the SYSTEM certificate store and click the Continue* button. If you don't see the SYSTEM certificate store, then you will need to refer to the document, How to Create the SYSTEM Store in DCM*, to create the SYSTEM certificate store first.
d)	Enter the SYSTEM certificate store password and click the Continue* button. If you cannot remember the password to the SYSTEM certificate store, you can click the Reset Password* button to change the password. After changing the password, you would enter the new password and click the Continue button to sign into the *SYSTEM certificate store. If you cannot successfully reset the password, please open a Service Request (PMR) with IBM here or call 1-800-IBM-SERV.
e)	After authenticating to the SYSTEM certificate store successfully, the page should refresh and display the Current Certificate Store* information as shown.
f)	On the left, vertical menu, click Fast Path and then click Work with CA Certificates.
g)	Scroll to the bottom of the Work with CA Certificates page and click the Import button.
h)	Input the IFS path to the CA certificate you would like to import in the Import file field and press the Continue button.
i)	Specify a certificate label name to uniquely identify the certificate in the *SYSTEM certificate store. The certificate label name must be unique and cannot already be used by another certificate in the certificate store. IBM recommends the certificate label be set to the Common Name of the certificate.
j)	If the CA certificate imports successfully, the screen will be refreshed with a message highlighted in green stating, "The certificate has been imported".
k)	Repeat steps 2f - 2j for any additional CA certificates in the SSL/TLS certificate chain.

3)

Configure the IBM i SMTP Client to trust the newly imported CA certificates.

a)	On the left, vertical menu, click Manage Applications and then click Define CA Trust list.
b)	Select the radio button next to Client and click the Continue button.
c)	Select the radio button next to IBM i TCP/IP SMTP Client and click the Define CA Trust List button. NOTE: If you don't see the IBM i TCP/IP SMTP Client application in the list, this indicates the SMTP Client application is configured NOT to use a CA Trust List. As a result, please proceed to Step 4.

4)

Assign a SSL/TLS certificate to the IBM i SMTP Client application in DCM.

a)	In a web browser, execute the following URL to access the Digital Certificate Manager (DCM) application: http://systemname:2001/QIBM/ICSS/Cert/Admin/qycucm1.ndm/main0 (Replace *systemname* with the TCP/IP hostname or IP address of your IBM i server)
b)	Click the "Select a Certificate Store" button.
c)	Select the radio button next to the SYSTEM certificate store and click the Continue* button. If you don't see the SYSTEM certificate store, then you will need to refer to the document, How to Create the SYSTEM Store in DCM*, to create the SYSTEM certificate store first.
d)	Enter the SYSTEM certificate store password and click the Continue* button. If you cannot remember the password to the SYSTEM certificate store, you can click the Reset Password* button to change the password. After changing the password, you would enter the new password and click the Continue button to sign into the *SYSTEM certificate store.
e)	After authenticating to the SYSTEM certificate store successfully, the page should refresh and display the Current Certificate Store* information.
f)	On the left, vertical menu, click Fast Path and then click Work with Server and Client Certificates.
g)	Select the radio button next to the SSL/TLS certificate you would like to assign to the IBM i SMTP Client application. If you would like to create a new certificate at this time, refer to the following document on how to create a self-signed certificate in DCM. How to create a basic self-signed certificate in DCM
h)	After selecting the certificate you would like to use, click the Assign to Applications button at the bottom of the table.
i)	Check the box next to the IBM i TCP/IP SMTP Client application in the list. Make sure you are select the SMTP Client application!!!
j)	After checking the box next to the IBM i TCP/IP SMTP Client application, scroll down to the bottom of the page and click on the Continue button.
h)	The page will refresh and the following message will be displayed. Click the OK button to complete the certificate assignment process.

5)

Set the SMTP Relay hostname for the "Forwarding Mailhub Server" SMTP Attribute.

CHGSMTPA FWDHUBSVR('<hostName>')

6)

Customize the Remote Port Value connected to by the IBM i SMTP Client when delivering emails.

Refer to the following IBM Technical document on how to configure the SMTP Client to deliver mail to a Mail Router/Fowarding Hub Server on a Port other than port 25.
How to Configure SMTP to Send Mail to a Mail Router that Listens on a Port Other Than Port 25

i.e.
ADDENVVAR ENVVAR(QIBM_SMTP_SERVER_PORT) VALUE('587') LEVEL(*SYS)

7)

Configure the User name and User password values used to authenticate to your Forwarding Mailhub Server or SMTP Relay.

IBM Navigator for i web application

a)	Open a web browser and go to the URL, http://:2004/ibm/console OR https://:2005/ibm/console, to display the IBM Navigator for i web application. If you do not see a log-in page appear, execute the following CL commands to ensure the ADMIN server is started and working properly: *ENDTCPSVR HTTP HTTPSVR(ADMIN)* *STRTCPSVR HTTP HTTPSVR(ADMIN)* If you continue to experience issues accessing the IBM Navigator for i web application, please open a Service Request (PMR) with IBM here or call 1-800-IBM-SERV.
b)	Enter your IBM i User ID and password to authenticate. Click the Log in button to continue.
c)	Click Network -> Servers -> TCP/IP Servers in the left, vertical menu. This will open up the TCP/IP Servers tab.
d)	Locate the SMTP Server, right-click and select Properties. This will open the SMTP Properties.
e)	Click the Authentication section in the SMTP Properties view.
f)	Under Logon information for relay server:, click the Add button.
g)	Enter in the same hostname value that is specified for the Forwarding Mailhub Server SMTP Attribute you customized in step 5. Then, enter the user name and password for the credentials required to authenticate to the SMTP relay. Click the OK button when complete to add and save the host logon information.
h)	After clicking the OK button, you should now see the hostname and User Name you just added. Click the OK button at the bottom of the SMTP Properties view to accept the SMTP properties changes. You will be prompted to restart the SMTP Server application.
i)	On the TCP/IP Servers tab with all the TCP/IP servers listed, right-click SMTP and click Stop. Click the OK button to close the informational message.
j)	On the TCP/IP Servers tab with all the TCP/IP servers listed, right-click SMTP and click Start . Click the OK button to close the informational message.

IBM i Access for Windows (System i Navigator)

1. Open i5/OS Navigator and go to Network>Servers>TCP/IP. Right click SMTP and select Properties:

i5 Navigator

2. From the General tab, add the name of the mail hub that the i5 will authenticate to. The command line equivalent is as follows:

CHGSMTPA FWDHUBSVR(MAILHUB)

SMTP Properties mailhub

3. In the Logon information for relay server, click the Add button and add the hostname for the mailhub, user name, and password that is used to authenticate to that mailhub. The command line equivalent is as follows:

ADDSMTPLE TYPE(*HOSTAUTH) HOSTNAME(MAILHUB) USERNAME(kswan) PASSWORD()

Add host logon information

4. Once this is all completed, restart the SMTP server either from the Navigator screen or with the following commands:

ENDTCPSVR *SMTP
STRTCPSVR *SMTP

8)

Congratulations! You have successfully configured your IBM i SMTP Client to relay all email to the SMTP relay host specified on the "Fowarding Mailhub Server" SMTP Attribute using the SSL certificates and authentication credentials configured.

If you still experience email delivery issues with the IBM i SMTP Client after the above configuration has been completed successfully, an IBM i SMTP Client trace can be gathered using the instructions in the URL, http://www.ibm.com/support/docview.wss?uid=nas8N1012636, to help determine the cause of your email delivery failures. Locate the QTMSSTRC spool file with the largest amount of pages. The spool file should be for the SMTP Client Pre Start Job or SMTP Client Daemon. These spool files will indicate why the SMTP relay connection, authentication, or delivery of email was unsuccessful.

Tips

How To Configure the SMTP Client To Use SMTP Authentication with a SMTP Relay

Troubleshooting

Problem

Environment

Resolving The Problem

Historical Number

Was this topic helpful?

Document Information

UID

Share your feedback

Need support?